openapi: 3.0.1
info:
title: PlanetScale API
description: |-
PlanetScale API
© 2026 PlanetScale, Inc.
version: v1
x-copyright: '© 2026 PlanetScale, Inc.'
paths:
/organizations:
get:
tags:
- Organizations
operationId: list_organizations
summary: List organizations
parameters:
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Gets the organizations for the current user
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the organization
name:
type: string
description: The name of the organization
billing_email:
type: string
description: The billing email of the organization
created_at:
type: string
description: When the organization was created
updated_at:
type: string
description: When the organization was last updated
plan:
type: string
description: The billing plan of the organization
valid_billing_info:
type: boolean
description: >-
Whether or not the organization's billing
information is valid
sso:
type: boolean
description: Whether or not SSO is enabled on the organization
sso_directory:
type: boolean
description: >-
Whether or not the organization uses an SSO
directory
single_tenancy:
type: boolean
description: >-
Whether or not the organization has single tenancy
enabled
managed_tenancy:
type: boolean
description: >-
Whether or not the organization has managed tenancy
enabled
has_past_due_invoices:
type: boolean
description: >-
Whether or not the organization has past due billing
invoices.
nullable: true
database_count:
type: integer
description: The number of databases in the organization
sso_portal_url:
type: string
description: The URL of the organization's SSO portal.
nullable: true
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: >-
Whether or not the IdP provider is be responsible
for managing roles in PlanetScale
invoice_budget_amount:
type: string
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: integer
description: The keyspace shard limit for the organization
has_card:
type: boolean
description: >-
Whether or not the organization has a payment method
on file
payment_info_required:
type: boolean
description: >-
Whether or not the organization requires payment
information
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- database_count
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
When using a service token, returns the list of organizations the
service token has access to. When using an OAuth token, returns the list
of organizations the user has access to.
### Authorization
A OAuth token must have at least one of the following scopes in
order to use this API endpoint:
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| User | `read_organizations` |
/organizations/{organization}:
get:
tags:
- Organizations
operationId: get_organization
summary: Get an organization
parameters:
- name: organization
in: path
required: true
description: 'Organization name slug from `list_organizations`. Example: `acme`.'
schema:
type: string
responses:
'200':
description: Returns an organization
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID for the organization
name:
type: string
description: The name of the organization
billing_email:
type: string
description: The billing email of the organization
created_at:
type: string
description: When the organization was created
updated_at:
type: string
description: When the organization was last updated
plan:
type: string
description: The billing plan of the organization
valid_billing_info:
type: boolean
description: >-
Whether or not the organization's billing information is
valid
sso:
type: boolean
description: Whether or not SSO is enabled on the organization
sso_directory:
type: boolean
description: Whether or not the organization uses an SSO directory
single_tenancy:
type: boolean
description: Whether or not the organization has single tenancy enabled
managed_tenancy:
type: boolean
description: >-
Whether or not the organization has managed tenancy
enabled
has_past_due_invoices:
type: boolean
description: >-
Whether or not the organization has past due billing
invoices.
nullable: true
database_count:
type: integer
description: The number of databases in the organization
sso_portal_url:
type: string
description: The URL of the organization's SSO portal.
nullable: true
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: >-
Whether or not the IdP provider is be responsible for
managing roles in PlanetScale
invoice_budget_amount:
type: string
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: integer
description: The keyspace shard limit for the organization
has_card:
type: boolean
description: >-
Whether or not the organization has a payment method on
file
payment_info_required:
type: boolean
description: >-
Whether or not the organization requires payment
information
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- database_count
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| User | `read_organizations` |
| Organization | `read_organization` |
patch:
tags:
- Organizations
operationId: update_organization
summary: Update an organization
parameters:
- name: organization
in: path
required: true
description: 'Organization name slug from `list_organizations`. Example: `acme`.'
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
billing_email:
type: string
description: The billing email for the organization
idp_managed_roles:
type: boolean
description: >-
Whether or not the IdP provider is be responsible for
managing roles in PlanetScale
invoice_budget_amount:
type: integer
description: The expected monthly budget for the organization
responses:
'200':
description: Returns the updated organization
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID for the organization
name:
type: string
description: The name of the organization
billing_email:
type: string
description: The billing email of the organization
created_at:
type: string
description: When the organization was created
updated_at:
type: string
description: When the organization was last updated
plan:
type: string
description: The billing plan of the organization
valid_billing_info:
type: boolean
description: >-
Whether or not the organization's billing information is
valid
sso:
type: boolean
description: Whether or not SSO is enabled on the organization
sso_directory:
type: boolean
description: Whether or not the organization uses an SSO directory
single_tenancy:
type: boolean
description: Whether or not the organization has single tenancy enabled
managed_tenancy:
type: boolean
description: >-
Whether or not the organization has managed tenancy
enabled
has_past_due_invoices:
type: boolean
description: >-
Whether or not the organization has past due billing
invoices.
nullable: true
database_count:
type: integer
description: The number of databases in the organization
sso_portal_url:
type: string
description: The URL of the organization's SSO portal.
nullable: true
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: >-
Whether or not the IdP provider is be responsible for
managing roles in PlanetScale
invoice_budget_amount:
type: string
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: integer
description: The keyspace shard limit for the organization
has_card:
type: boolean
description: >-
Whether or not the organization has a payment method on
file
payment_info_required:
type: boolean
description: >-
Whether or not the organization requires payment
information
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- database_count
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
### Authorization
A OAuth token must have at least one of the following scopes in
order to use this API endpoint:
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
/organizations/{organization}/audit-log:
get:
tags:
- Organizations
operationId: list_audit_logs
summary: List audit logs
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: starting_after
in: query
description: If provided, returns results after the specified cursor
schema:
type: string
- name: ending_before
in: query
description: If provided, returns results before the specified cursor
schema:
type: string
- name: limit
in: query
description: If provided, specifies the number of returned results (max 100)
schema:
type: integer
default: 25
responses:
'200':
description: Returns the audit log events
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
has_next:
type: boolean
description: Whether there is a next page of results
has_prev:
type: boolean
description: Whether there is a previous page of results
cursor_start:
type: string
description: >-
The ID of the first object in the current results, or null
when there are no results
nullable: true
cursor_end:
type: string
description: >-
The ID of the last object in the current results, or null
when there are no results
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the audit log
actor_id:
type: string
description: The ID of the actor
nullable: true
actor_type:
type: string
description: >-
The type of the actor. Such as 'User' or
'ServiceToken'
nullable: true
auditable_id:
type: string
description: The ID of the auditable object
nullable: true
auditable_type:
type: string
description: >-
The type of the auditable. Such as 'Organization' or
'Database'
nullable: true
target_id:
type: string
description: The ID of the target
nullable: true
target_type:
type: string
description: >-
The type of the target. Such as 'DatabaseBranch' or
'DatabaseBranchPassword'
nullable: true
location:
type: string
description: The location of the actor based on their IP address
nullable: true
target_display_name:
type: string
description: The name of the target
nullable: true
audit_action:
type: string
description: The action that was taken
action:
type: string
description: The action that was taken
actor_display_name:
type: string
description: The name of the actor
auditable_display_name:
type: string
description: The name of the auditable object
remote_ip:
type: string
description: The IP address of the actor
nullable: true
created_at:
type: string
description: When the audit log was created
updated_at:
type: string
description: When the audit log was last updated
metadata:
type: object
additionalProperties: true
description: >-
Additional metadata containing details about the
change
nullable: true
required:
- id
- actor_id
- actor_type
- auditable_id
- auditable_type
- target_id
- target_type
- location
- target_display_name
- audit_action
- action
- actor_display_name
- auditable_display_name
- remote_ip
- created_at
- updated_at
- metadata
required:
- type
- has_next
- has_prev
- cursor_start
- cursor_end
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`read_audit_logs`
/organizations/{organization}/cluster-size-skus:
get:
tags:
- Organizations
operationId: list_cluster_size_skus
summary: List available cluster sizes
parameters:
- name: organization
in: path
required: true
description: 'Organization name slug from `list_organizations`. Example: `acme`.'
schema:
type: string
- name: engine
in: query
description: The database engine to filter by. Defaults to 'mysql'.
schema:
type: string
enum:
- mysql
- postgresql
- name: rates
in: query
description: Whether to include pricing rates in the response. Defaults to false.
schema:
type: boolean
- name: region
in: query
description: >-
The region slug to get rates for. If not specified, uses the
organization's default region.
schema:
type: string
responses:
'200':
description: Returns available cluster sizes with optional pricing rates
headers: {}
content:
application/json:
schema:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the cluster SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The number of CPUs
storage:
type: integer
description: The amount of storage in bytes
nullable: true
ram:
type: integer
description: The amount of memory in bytes
metal:
type: boolean
description: Whether or not the cluster SKU is Metal
enabled:
type: boolean
description: >-
Whether or not the cluster SKU is enabled for the
organization
provider:
type: string
description: The provider of the cluster SKU (nil, AWS or GCP)
nullable: true
default_vtgate:
type: string
description: The default vtgate size for the cluster SKU
default_vtgate_rate:
type: number
description: The default vtgate rate for the cluster SKU
nullable: true
replica_rate:
type: number
description: The replica rate for the cluster SKU
nullable: true
rate:
type: number
description: The rate for the cluster SKU
nullable: true
sort_order:
type: integer
description: The sort order of the cluster SKU
architecture:
type: string
description: >-
The architecture of the cluster SKU (null, x86_64 or
arm64)
nullable: true
development:
type: boolean
description: Whether or not the cluster SKU is a development SKU
production:
type: boolean
description: Whether or not the cluster SKU is a production SKU
required:
- name
- display_name
- cpu
- storage
- ram
- metal
- enabled
- provider
- default_vtgate
- default_vtgate_rate
- sort_order
- development
- production
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
List available cluster sizes for an organization
### 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**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| User | `read_organizations` |
| Organization | `read_organization` |
/organizations/{organization}/databases:
get:
tags:
- Databases
operationId: list_databases
summary: List databases
parameters:
- name: organization
in: path
required: true
description: 'Organization name slug from `list_organizations`. Example: `acme`.'
schema:
type: string
- name: q
in: query
description: Search term to filter databases by name
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Retrieves the databases for an organization
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: >-
The URL to retrieve this database's branches via the
API
branches_count:
type: integer
description: The total number of database branches
open_schema_recommendations_count:
type: integer
description: The total number of schema recommendations
development_branches_count:
type: integer
description: The total number of database development branches
production_branches_count:
type: integer
description: The total number of database production branches
issues_count:
type: integer
description: The total number of ongoing issues within a database
nullable: true
multiple_admins_required_for_deletion:
type: boolean
description: >-
If the database requires multiple admins for
deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: >-
If the database has reached its backup restored
branch limit
at_development_branch_usage_limit:
type: boolean
description: >-
If the database has reached its development branch
limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
nullable: true
finished_at:
type: string
description: When the import finished
nullable: true
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
required:
- hostname
- port
- database
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
nullable: true
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
html_url:
type: string
description: >-
The URL to see this database's branches in the web
UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: >-
Whether an approval is required to deploy schema
changes to this database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
config_changing:
type: boolean
description: True if a config change is in progress
config_change_queued:
type: boolean
description: >-
True if a config change is queued for maintenance
window
allow_data_branching:
type: boolean
description: >-
Whether seeding branches with data is enabled for
all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: >-
Whether to automatically manage Rails migrations
during deploy requests.
nullable: true
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: >-
Whether web console is enabled for production
branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data.
nullable: true
migration_framework:
type: string
description: Framework used for applying migrations.
nullable: true
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- resizing
- resize_queued
- config_changing
- config_change_queued
- allow_data_branching
- foreign_keys_enabled
- restrict_branch_region
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- created_at
- updated_at
- schema_last_updated_at
- kind
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_database`, `delete_database`, `write_database`, `read_branch`, `delete_branch`, `create_branch`, `delete_production_branch`, `connect_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `delete_branch_password`, `delete_production_branch_password`, `delete_production_read_only_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_comment`, `create_comment`, `restore_backup`, `restore_production_branch_backup`, `read_backups`, `write_backups`, `delete_backups`, `delete_production_branch_backups`, `write_branch_vschema`, `write_production_branch_vschema`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
post:
tags:
- Databases
operationId: create_database
summary: Create a database
parameters:
- name: organization
in: path
required: true
description: 'Organization name slug from `list_organizations`. Example: `acme`.'
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the database
region:
type: string
description: >-
The region the database will be deployed in. If left blank,
defaults to the organization's default region.
cluster_size:
type: string
description: >-
The database cluster size name (e.g., 'PS_10', 'PS_80'). Use
the 'List available cluster sizes' endpoint to get available
options for your organization.
/v1/organizations/:organization/cluster-size-skus
replicas:
type: integer
description: >-
The number of replicas for the database. 0 for non-HA, 2+
for HA.
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database to create.
major_version:
type: string
description: >-
For PostgreSQL databases, the PostgreSQL major version to
use for the database. Defaults to the latest available major
version.
storage:
type: object
properties:
minimum_storage_bytes:
type: integer
description: The initial minimum storage size in bytes.
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes for autoscaling.
required:
- name
- cluster_size
responses:
'201':
description: Returns the created database
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
branches_count:
type: integer
description: The total number of database branches
open_schema_recommendations_count:
type: integer
description: The total number of schema recommendations
development_branches_count:
type: integer
description: The total number of database development branches
production_branches_count:
type: integer
description: The total number of database production branches
issues_count:
type: integer
description: The total number of ongoing issues within a database
nullable: true
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: >-
If the database has reached its backup restored branch
limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
nullable: true
finished_at:
type: string
description: When the import finished
nullable: true
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
required:
- hostname
- port
- database
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
nullable: true
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
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: >-
Whether an approval is required to deploy schema changes
to this database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
config_changing:
type: boolean
description: True if a config change is in progress
config_change_queued:
type: boolean
description: True if a config change is queued for maintenance window
allow_data_branching:
type: boolean
description: >-
Whether seeding branches with data is enabled for all
branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: >-
Whether to automatically manage Rails migrations during
deploy requests.
nullable: true
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data.
nullable: true
migration_framework:
type: string
description: Framework used for applying migrations.
nullable: true
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- resizing
- resize_queued
- config_changing
- config_change_queued
- allow_data_branching
- foreign_keys_enabled
- restrict_branch_region
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- created_at
- updated_at
- schema_last_updated_at
- kind
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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_databases`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `create_databases` |
/organizations/{organization}/databases/{database}:
get:
tags:
- Databases
operationId: get_database
summary: Get a database
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
responses:
'200':
description: Returns a database
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
branches_count:
type: integer
description: The total number of database branches
open_schema_recommendations_count:
type: integer
description: The total number of schema recommendations
development_branches_count:
type: integer
description: The total number of database development branches
production_branches_count:
type: integer
description: The total number of database production branches
issues_count:
type: integer
description: The total number of ongoing issues within a database
nullable: true
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: >-
If the database has reached its backup restored branch
limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
nullable: true
finished_at:
type: string
description: When the import finished
nullable: true
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
required:
- hostname
- port
- database
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
nullable: true
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
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: >-
Whether an approval is required to deploy schema changes
to this database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
config_changing:
type: boolean
description: True if a config change is in progress
config_change_queued:
type: boolean
description: True if a config change is queued for maintenance window
allow_data_branching:
type: boolean
description: >-
Whether seeding branches with data is enabled for all
branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: >-
Whether to automatically manage Rails migrations during
deploy requests.
nullable: true
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data.
nullable: true
migration_framework:
type: string
description: Framework used for applying migrations.
nullable: true
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- resizing
- resize_queued
- config_changing
- config_change_queued
- allow_data_branching
- foreign_keys_enabled
- restrict_branch_region
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- created_at
- updated_at
- schema_last_updated_at
- kind
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_database`, `delete_database`, `write_database`, `read_branch`, `delete_branch`, `create_branch`, `delete_production_branch`, `connect_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `delete_branch_password`, `delete_production_branch_password`, `delete_production_read_only_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_comment`, `create_comment`, `restore_backup`, `restore_production_branch_backup`, `read_backups`, `write_backups`, `delete_backups`, `delete_production_branch_backups`, `write_branch_vschema`, `write_production_branch_vschema`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
patch:
tags:
- Databases
operationId: update_database_settings
summary: Update database settings
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
requestBody:
content:
application/json:
schema:
type: object
properties:
new_name:
type: string
description: The name to update the database to
automatic_migrations:
type: boolean
description: >-
Whether or not to copy migration data to new branches and in
deploy requests. (Vitess only)
migration_framework:
type: string
description: A migration framework to use on the database. (Vitess only)
migration_table_name:
type: string
description: >-
Name of table to use as migration table for the database.
(Vitess only)
require_approval_for_deploy:
type: boolean
description: >-
Whether or not deploy requests must be approved by a
database administrator other than the request creator
restrict_branch_region:
type: boolean
description: >-
Whether or not to limit branch creation to the same region
as the one selected during database creation.
allow_data_branching:
type: boolean
description: >-
Whether or not data branching is allowed on the database.
(Vitess only)
allow_foreign_key_constraints:
type: boolean
description: >-
Whether or not foreign key constraints are allowed on the
database. (Vitess only)
insights_raw_queries:
type: boolean
description: >-
Whether or not full queries should be collected from the
database
production_branch_web_console:
type: boolean
description: >-
Whether or not the web console can be used on the production
branch of the database
default_branch:
type: string
description: The default branch of the database
responses:
'200':
description: Returns the updated database
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
branches_count:
type: integer
description: The total number of database branches
open_schema_recommendations_count:
type: integer
description: The total number of schema recommendations
development_branches_count:
type: integer
description: The total number of database development branches
production_branches_count:
type: integer
description: The total number of database production branches
issues_count:
type: integer
description: The total number of ongoing issues within a database
nullable: true
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: >-
If the database has reached its backup restored branch
limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
nullable: true
finished_at:
type: string
description: When the import finished
nullable: true
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
required:
- hostname
- port
- database
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
nullable: true
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
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: >-
Whether an approval is required to deploy schema changes
to this database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
config_changing:
type: boolean
description: True if a config change is in progress
config_change_queued:
type: boolean
description: True if a config change is queued for maintenance window
allow_data_branching:
type: boolean
description: >-
Whether seeding branches with data is enabled for all
branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: >-
Whether to automatically manage Rails migrations during
deploy requests.
nullable: true
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data.
nullable: true
migration_framework:
type: string
description: Framework used for applying migrations.
nullable: true
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- resizing
- resize_queued
- config_changing
- config_change_queued
- allow_data_branching
- foreign_keys_enabled
- restrict_branch_region
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- created_at
- updated_at
- schema_last_updated_at
- kind
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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` |
delete:
tags:
- Databases
operationId: delete_database
summary: Delete a database
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
responses:
'204':
description: Deletes a database
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`delete_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `delete_databases` |
| Database | `delete_database` |
/organizations/{organization}/databases/{database}/backup-policies:
get:
tags:
- BackupPolicies
operationId: list_backup_policies
summary: List backup policies
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: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns backup policies for the database
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: >-
Whether the policy is for production or development
branches
retention_value:
type: integer
description: >-
A number value for the retention period of the
backup policy
retention_unit:
type: string
description: >-
The unit for the retention period of the backup
policy
frequency_value:
type: integer
description: >-
A number value for the frequency of the backup
policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: >-
The time of day that the backup is scheduled, in
HH:MM format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0 is
Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled. 0 is
the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_backups` |
| Database | `read_backups` |
post:
tags:
- BackupPolicies
operationId: create_backup_policy
summary: Create a backup policy
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
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
enum:
- hour
- day
- week
- month
- year
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
enum:
- hour
- day
- week
- month
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: >-
The time of day that the backup is scheduled, in HH:MM
format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0 is Sunday, 6
is Saturday
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled. 0 is the
first week, 3 is the fourth week
responses:
'201':
description: Returns the created backup policy
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: >-
Whether the policy is for production or development
branches
retention_value:
type: integer
description: >-
A number value for the retention period of the backup
policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: >-
The time of day that the backup is scheduled, in HH:MM
format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0 is Sunday,
6 is Saturday
nullable: true
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled. 0 is the
first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_backups` |
| Database | `write_backups` |
/organizations/{organization}/databases/{database}/backup-policies/{id}:
get:
tags:
- BackupPolicies
operationId: get_backup_policy
summary: Get a backup policy
parameters:
- name: id
in: path
required: true
description: The ID of the backup policy
schema:
type: string
- 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
responses:
'200':
description: Returns a backup policy
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: >-
Whether the policy is for production or development
branches
retention_value:
type: integer
description: >-
A number value for the retention period of the backup
policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: >-
The time of day that the backup is scheduled, in HH:MM
format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0 is Sunday,
6 is Saturday
nullable: true
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled. 0 is the
first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_backups` |
| Database | `read_backups` |
patch:
tags:
- BackupPolicies
operationId: update_backup_policy
summary: Update a backup policy
parameters:
- name: id
in: path
required: true
description: The ID of the backup policy
schema:
type: string
- 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
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
enum:
- hour
- day
- week
- month
- year
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
enum:
- hour
- day
- week
- month
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: >-
The time of day that the backup is scheduled, in HH:MM
format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0 is Sunday, 6
is Saturday
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled. 0 is the
first week, 3 is the fourth week
responses:
'200':
description: Returns the updated backup policy
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: >-
Whether the policy is for production or development
branches
retention_value:
type: integer
description: >-
A number value for the retention period of the backup
policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: >-
The time of day that the backup is scheduled, in HH:MM
format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0 is Sunday,
6 is Saturday
nullable: true
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled. 0 is the
first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_backups` |
| Database | `write_backups` |
delete:
tags:
- BackupPolicies
operationId: delete_backup_policy
summary: Delete a backup policy
parameters:
- name: id
in: path
required: true
description: The ID of the backup policy
schema:
type: string
- 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
responses:
'204':
description: Returns no content
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_backups` |
| Database | `write_backups` |
/organizations/{organization}/databases/{database}/branches:
get:
tags:
- Database branches
operationId: list_branches
summary: List branches
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: q
in: query
description: Search branches by name
schema:
type: string
- name: production
in: query
description: Filter branches by production status
schema:
type: boolean
- name: safe_migrations
in: query
description: Filter branches by safe migrations (DDL protection)
schema:
type: boolean
- name: order
in: query
description: Order branches by created_at time
schema:
type: string
enum:
- asc
- desc
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns database branches
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
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
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
post:
tags:
- Database branches
operationId: create_branch
summary: Create a 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.
create_database_if_missing:
type: boolean
description: >-
Create a new database for the branch if the database does
not exist. Defaults to false.
kind:
type: string
enum:
- mysql
- postgresql
description: >-
The kind of branch to create. Required when
create_database_if_missing is set.
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
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` |
/organizations/{organization}/databases/{database}/branches/{branch}:
get:
tags:
- Database branches
operationId: get_branch
summary: Get a branch
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
responses:
'200':
description: Returns information about a 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
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
patch:
tags:
- Database branches
operationId: update_branch
summary: Update a 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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
new_name:
type: string
description: The name to update the branch
required:
- new_name
responses:
'200':
description: Returns the updated 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
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_branches` |
| Database | `write_branches` |
| Branch | `write_branch` |
delete:
tags:
- Database branches
operationId: delete_branch
summary: Delete a 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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: delete_descendants
in: query
description: >-
If true, recursively delete all descendant branches along with this
branch
schema:
type: boolean
responses:
'204':
description: Delete a branch
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`delete_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `delete_branches`, `delete_production_branches` |
| Database | `delete_branches`, `delete_production_branches` |
| Branch | `delete_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/backups:
get:
tags:
- Backups
operationId: list_backups
summary: List backups
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: all
in: query
description: Whether to include all backups, including deleted ones
schema:
type: boolean
- name: state
in: query
description: Filter backups by state
schema:
type: string
enum:
- pending
- running
- success
- failed
- canceled
- ignored
- name: policy
in: query
description: Filter backups by backup policy ID
schema:
type: string
- name: from
in: query
description: Filter backups started after this date (e.g. 2023-01-01T00:00:00Z)
schema:
type: string
- name: to
in: query
description: Filter backups started before this date (e.g. 2023-01-31T23:59:59Z)
schema:
type: string
- name: running_at
in: query
description: >-
Filter backups that are running during a specific time (e.g.
2023-01-01T00:00:00Z..2023-01-01T23:59:59Z)
schema:
type: string
- name: production
in: query
description: Filter backups by production branch
schema:
type: boolean
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns database branch backups
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the backup
name:
type: string
description: The name of the backup
state:
type: string
enum:
- pending
- running
- success
- failed
- canceled
- ignored
description: The current state of the backup
size:
type: integer
description: The size of the backup in bytes
estimated_storage_cost:
type: number
description: The estimated storage cost of the backup
created_at:
type: string
description: When the backup was created
updated_at:
type: string
description: When the backup was last updated
started_at:
type: string
description: When the backup started
nullable: true
expires_at:
type: string
description: When the backup expires
nullable: true
completed_at:
type: string
description: When the backup completed
nullable: true
deleted_at:
type: string
description: When the backup was deleted
nullable: true
pvc_size:
type: integer
description: Size of the PVC used for the backup
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
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
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
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: >-
Whether the policy is for production or
development branches
retention_value:
type: integer
description: >-
A number value for the retention period of the
backup policy
retention_unit:
type: string
description: >-
The unit for the retention period of the backup
policy
frequency_value:
type: integer
description: >-
A number value for the frequency of the backup
policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: >-
The time of day that the backup is scheduled, in
HH:MM format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0
is Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled.
0 is the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
nullable: true
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
nullable: true
url:
type: string
description: >-
The URL to the schema snapshot in the
PlanetScale app
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
nullable: true
database_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
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- protected
- required
- restored_branches
- actor
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_backups` |
| Database | `read_backups` |
| Branch | `read_backups` |
post:
tags:
- Backups
operationId: create_backup
summary: Create a backup
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name for the backup
retention_unit:
type: string
enum:
- hour
- day
- week
- month
- year
description: Unit for the retention period of the backup
retention_value:
type: integer
description: >-
Value between `1` and `1000` for the retention period of the
backup (i.e retention_value `6` and retention_unit `hour`
means 6 hours)
emergency:
type: boolean
description: >-
Whether the backup is an immediate backup that may affect
database performance. Emergency backups are only supported
for PostgreSQL databases.
responses:
'201':
description: Returns the created database branch backup
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the backup
name:
type: string
description: The name of the backup
state:
type: string
enum:
- pending
- running
- success
- failed
- canceled
- ignored
description: The current state of the backup
size:
type: integer
description: The size of the backup in bytes
estimated_storage_cost:
type: number
description: The estimated storage cost of the backup
created_at:
type: string
description: When the backup was created
updated_at:
type: string
description: When the backup was last updated
started_at:
type: string
description: When the backup started
nullable: true
expires_at:
type: string
description: When the backup expires
nullable: true
completed_at:
type: string
description: When the backup completed
nullable: true
deleted_at:
type: string
description: When the backup was deleted
nullable: true
pvc_size:
type: integer
description: Size of the PVC used for the backup
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
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
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
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: >-
Whether the policy is for production or development
branches
retention_value:
type: integer
description: >-
A number value for the retention period of the backup
policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: >-
The time of day that the backup is scheduled, in HH:MM
format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0 is
Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled. 0 is
the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
nullable: true
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
nullable: true
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
nullable: true
database_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
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- protected
- required
- restored_branches
- actor
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_backups` |
| Database | `write_backups` |
| Branch | `write_backups` |
/organizations/{organization}/databases/{database}/branches/{branch}/backups/{id}:
get:
tags:
- Backups
operationId: get_backup
summary: Get a backup
parameters:
- name: id
in: path
required: true
description: The ID for the backup
schema:
type: string
- 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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
'200':
description: Returns a database branch backup
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the backup
name:
type: string
description: The name of the backup
state:
type: string
enum:
- pending
- running
- success
- failed
- canceled
- ignored
description: The current state of the backup
size:
type: integer
description: The size of the backup in bytes
estimated_storage_cost:
type: number
description: The estimated storage cost of the backup
created_at:
type: string
description: When the backup was created
updated_at:
type: string
description: When the backup was last updated
started_at:
type: string
description: When the backup started
nullable: true
expires_at:
type: string
description: When the backup expires
nullable: true
completed_at:
type: string
description: When the backup completed
nullable: true
deleted_at:
type: string
description: When the backup was deleted
nullable: true
pvc_size:
type: integer
description: Size of the PVC used for the backup
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
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
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
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: >-
Whether the policy is for production or development
branches
retention_value:
type: integer
description: >-
A number value for the retention period of the backup
policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: >-
The time of day that the backup is scheduled, in HH:MM
format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0 is
Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled. 0 is
the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
nullable: true
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
nullable: true
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
nullable: true
database_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
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- protected
- required
- restored_branches
- actor
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_backups` |
| Database | `read_backups` |
| Branch | `read_backups` |
patch:
tags:
- Backups
operationId: update_backup
summary: Update a backup
parameters:
- name: id
in: path
required: true
description: The ID of the backup
schema:
type: string
- 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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
protected:
type: boolean
description: Whether the backup is protected from deletion or not
responses:
'200':
description: Returns the backup
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the backup
name:
type: string
description: The name of the backup
state:
type: string
enum:
- pending
- running
- success
- failed
- canceled
- ignored
description: The current state of the backup
size:
type: integer
description: The size of the backup in bytes
estimated_storage_cost:
type: number
description: The estimated storage cost of the backup
created_at:
type: string
description: When the backup was created
updated_at:
type: string
description: When the backup was last updated
started_at:
type: string
description: When the backup started
nullable: true
expires_at:
type: string
description: When the backup expires
nullable: true
completed_at:
type: string
description: When the backup completed
nullable: true
deleted_at:
type: string
description: When the backup was deleted
nullable: true
pvc_size:
type: integer
description: Size of the PVC used for the backup
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
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
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
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: >-
Whether the policy is for production or development
branches
retention_value:
type: integer
description: >-
A number value for the retention period of the backup
policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: >-
The time of day that the backup is scheduled, in HH:MM
format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0 is
Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled. 0 is
the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
nullable: true
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
nullable: true
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
nullable: true
database_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
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- protected
- required
- restored_branches
- actor
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_backups` |
| Database | `write_backups` |
| Branch | `write_backups` |
delete:
tags:
- Backups
operationId: delete_backup
summary: Delete a backup
parameters:
- name: id
in: path
required: true
description: The ID of the backup
schema:
type: string
- 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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
'204':
description: Delete a backup
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`delete_backups`, `delete_production_branch_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `delete_backups`, `delete_production_branch_backups` |
| Database | `delete_backups`, `delete_production_branch_backups` |
| Branch | `delete_backups` |
/organizations/{organization}/databases/{database}/branches/{branch}/bouncer-resizes:
get:
tags:
- api-branch_bouncer_resizes
operationId: list_branch_bouncer_resize_requests
summary: Get bouncer resize requests
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
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns bouncer resize requests
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: >-
The number of replicas per cell for the bouncer
after the resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: >-
The number of replicas per cell for the bouncer
before the resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
nullable: true
completed_at:
type: string
description: The time the bouncer resize completed
nullable: true
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
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
bouncer:
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
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
required:
- id
- state
- replicas_per_cell
- parameters
- previous_replicas_per_cell
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/bouncers:
get:
tags:
- Bouncers
operationId: list_bouncers
summary: List bouncers
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
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns bouncers
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer
name:
type: string
description: The name of the bouncer
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The instance type the bouncer targets
replicas_per_cell:
type: integer
description: The count of replicas in each cell
created_at:
type: string
description: When the bouncer was created
updated_at:
type: string
description: When the bouncer was updated
deleted_at:
type: string
description: When the bouncer was deleted
nullable: true
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
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
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
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:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
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
updated_at:
type: string
description: When the parameter was last updated
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
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options 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
- step
- url
- options
- actor
required:
- id
- name
- sku
- target
- replicas_per_cell
- created_at
- updated_at
- deleted_at
- actor
- branch
- parameters
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
post:
tags:
- Bouncers
operationId: create_bouncer
summary: Create a bouncer
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 bouncer name
target:
type: string
description: The type of server the bouncer targets
bouncer_size:
type: string
description: The size SKU for the bouncer
replicas_per_cell:
type: integer
description: The number of replica servers per cell
responses:
'200':
description: Returns the new bouncer
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the bouncer
name:
type: string
description: The name of the bouncer
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The instance type the bouncer targets
replicas_per_cell:
type: integer
description: The count of replicas in each cell
created_at:
type: string
description: When the bouncer was created
updated_at:
type: string
description: When the bouncer was updated
deleted_at:
type: string
description: When the bouncer was deleted
nullable: true
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
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
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
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:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
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
updated_at:
type: string
description: When the parameter was last updated
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
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options 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
- step
- url
- options
- actor
required:
- id
- name
- sku
- target
- replicas_per_cell
- created_at
- updated_at
- deleted_at
- actor
- branch
- parameters
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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` |
/organizations/{organization}/databases/{database}/branches/{branch}/bouncers/{bouncer}:
get:
tags:
- Bouncers
operationId: get_bouncer
summary: Get a bouncer
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
- name: bouncer
in: path
required: true
description: The name of the bouncer
schema:
type: string
responses:
'200':
description: Returns a bouncer
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the bouncer
name:
type: string
description: The name of the bouncer
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The instance type the bouncer targets
replicas_per_cell:
type: integer
description: The count of replicas in each cell
created_at:
type: string
description: When the bouncer was created
updated_at:
type: string
description: When the bouncer was updated
deleted_at:
type: string
description: When the bouncer was deleted
nullable: true
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
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
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
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:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
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
updated_at:
type: string
description: When the parameter was last updated
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
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options 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
- step
- url
- options
- actor
required:
- id
- name
- sku
- target
- replicas_per_cell
- created_at
- updated_at
- deleted_at
- actor
- branch
- parameters
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
delete:
tags:
- Bouncers
operationId: delete_bouncer
summary: Delete a bouncer
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
- name: bouncer
in: path
required: true
description: The name of the bouncer
schema:
type: string
responses:
'204':
description: Deletes the bouncer
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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` |
/organizations/{organization}/databases/{database}/branches/{branch}/bouncers/{bouncer}/resizes:
get:
tags:
- Bouncer resizes
operationId: list_bouncer_resize_requests
summary: Get bouncer resize requests
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
- name: bouncer
in: path
required: true
description: The name of the bouncer
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns bouncer resize requests
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: >-
The number of replicas per cell for the bouncer
after the resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: >-
The number of replicas per cell for the bouncer
before the resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
nullable: true
completed_at:
type: string
description: The time the bouncer resize completed
nullable: true
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
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
bouncer:
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
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
required:
- id
- state
- replicas_per_cell
- parameters
- previous_replicas_per_cell
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
patch:
tags:
- Bouncer resizes
operationId: update_bouncer_resize_request
summary: Upsert a bouncer resize request
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
- name: bouncer
in: path
required: true
description: The name of the bouncer
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
bouncer_size:
type: string
description: >-
The bouncer size SKU name (e.g., 'PGB_5', 'PGB_10',
'PGB_20', 'PGB_40', 'PGB_80', 'PGB_160'). Defaults to
'PGB_5'.
replicas_per_cell:
type: integer
description: >-
The number of PgBouncers per availability zone. Defaults to
1.
parameters:
type: object
additionalProperties: true
description: >-
Bouncer configuration parameters nested by namespace (e.g.,
{"pgbouncer": {"default_pool_size": "100"}}). Use the 'List
cluster parameters' endpoint to retrieve available
parameters. Only parameters with namespace 'pgbouncer' can
be updated.
responses:
'200':
description: Returns bouncer resize request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: >-
The number of replicas per cell for the bouncer after the
resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: >-
The number of replicas per cell for the bouncer before the
resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
nullable: true
completed_at:
type: string
description: The time the bouncer resize completed
nullable: true
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
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
bouncer:
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
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
required:
- id
- state
- replicas_per_cell
- parameters
- previous_replicas_per_cell
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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` |
delete:
tags:
- Bouncer resizes
operationId: cancel_bouncer_resize_request
summary: Cancel a resize request
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
- name: bouncer
in: path
required: true
description: The name of the bouncer
schema:
type: string
responses:
'204':
description: Cancels a resize request
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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` |
/organizations/{organization}/databases/{database}/branches/{branch}/changes:
get:
tags:
- Branch changes
operationId: list_branch_change_requests
summary: Get branch change requests
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
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns branch change requests
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the branch change request
restart:
items:
type: integer
type: array
description: >-
The ports requiring a restart when changes are
applied
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
nullable: true
completed_at:
type: string
description: The time the branch change request completed
nullable: true
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
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
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: >-
The previous SKU representing the branch cluster for
display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: >-
Whether storage shrinking is enabled when
autoscaling is enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
required:
- id
- restart
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_parameters
- minimum_storage_bytes
- maximum_storage_bytes
- storage_autoscaling
- storage_shrinking
- storage_type
- storage_iops
- storage_throughput_mibs
- previous_minimum_storage_bytes
- previous_maximum_storage_bytes
- previous_storage_autoscaling
- previous_storage_shrinking
- previous_storage_type
- previous_storage_iops
- previous_storage_throughput_mibs
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
patch:
tags:
- Branch changes
operationId: update_branch_change_request
summary: Upsert a change request
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:
cluster_size:
type: string
description: >-
The size of the cluster. Available sizes can be found using
the 'List cluster sizes' endpoint.
replicas:
type: integer
description: The total number of replicas
parameters:
type: object
additionalProperties: true
description: >-
Cluster configuration parameters nested by namespace (e.g.,
{"pgconf": {"max_connections": "200"}}). Use the 'List
cluster parameters' endpoint to retrieve available
parameters. Supported namespaces include 'patroni',
'pgconf', and 'pgbouncer'.
responses:
'200':
description: Returns the branch change request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch change request
restart:
items:
type: integer
type: array
description: The ports requiring a restart when changes are applied
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
nullable: true
completed_at:
type: string
description: The time the branch change request completed
nullable: true
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
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
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: >-
The previous SKU representing the branch cluster for
display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: >-
Whether storage shrinking is enabled when autoscaling is
enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
required:
- id
- restart
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_parameters
- minimum_storage_bytes
- maximum_storage_bytes
- storage_autoscaling
- storage_shrinking
- storage_type
- storage_iops
- storage_throughput_mibs
- previous_minimum_storage_bytes
- previous_maximum_storage_bytes
- previous_storage_autoscaling
- previous_storage_shrinking
- previous_storage_type
- previous_storage_iops
- previous_storage_throughput_mibs
'204':
description: No changes to apply
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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` |
/organizations/{organization}/databases/{database}/branches/{branch}/changes/{id}:
get:
tags:
- Branch changes
operationId: get_branch_change_request
summary: Get a branch change request
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
- name: id
in: path
required: true
description: The ID of the change request
schema:
type: string
responses:
'200':
description: Returns a branch change request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch change request
restart:
items:
type: integer
type: array
description: The ports requiring a restart when changes are applied
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
nullable: true
completed_at:
type: string
description: The time the branch change request completed
nullable: true
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
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
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: >-
The previous SKU representing the branch cluster for
display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: >-
Whether storage shrinking is enabled when autoscaling is
enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
required:
- id
- restart
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_parameters
- minimum_storage_bytes
- maximum_storage_bytes
- storage_autoscaling
- storage_shrinking
- storage_type
- storage_iops
- storage_throughput_mibs
- previous_minimum_storage_bytes
- previous_maximum_storage_bytes
- previous_storage_autoscaling
- previous_storage_shrinking
- previous_storage_type
- previous_storage_iops
- previous_storage_throughput_mibs
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/cluster:
patch:
tags:
- Database branches
operationId: update_branch_cluster_config
summary: Change a branch cluster configuration
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
- name: branch
in: path
required: true
description: The name of the branch to configure
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
cluster_size:
type: string
description: 'The new size of the database cluster: PS_10, PS_20,…'
required:
- cluster_size
responses:
'204':
description: Returns an empty response body
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`write_database`
/organizations/{organization}/databases/{database}/branches/{branch}/demote:
post:
tags:
- Database branches
operationId: demote_branch
summary: Demote a 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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
'200':
description: Returns a development 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
description: >-
Demotes a branch from production to development
### 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**
`connect_production_branch`, `demote_branches`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `demote_branches` |
| Database | `demote_branches` |
/organizations/{organization}/databases/{database}/branches/{branch}/extensions:
get:
tags:
- Cluster extensions
operationId: list_extensions
summary: List cluster extensions
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
responses:
'200':
description: Returns cluster extensions
headers: {}
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the extension
name:
type: string
description: The name of the extension
description:
type: string
description: The description of the extension
internal:
type: boolean
description: The internal state of the extension
shared_preload_allowed:
type: boolean
description: >-
Whether the extension can be added to
shared_preload_libraries
url:
type: string
description: The URL of the extension
available:
type: boolean
description: >-
Whether the extension is available on the current
cluster image
unavailable_reason:
type: string
description: >-
The reason the extension is unavailable (e.g.,
'container_upgrade_required')
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
namespace:
type: string
enum:
- patroni
- pgconf
- pgbouncer
description: The namespace of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
extension:
type: boolean
description: Configures an extension
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- seconds
- select
- string
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
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
updated_at:
type: string
description: When the parameter was last updated
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
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options 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
- name
- display_name
- namespace
- category
- description
- extension
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
required:
- id
- name
- description
- internal
- shared_preload_allowed
- url
- available
- unavailable_reason
- parameters
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/keyspaces:
get:
tags:
- Database branch keyspaces
operationId: list_keyspaces
summary: Get keyspaces
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns keyspaces
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: >-
The SKU representing the keyspace cluster size for
display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
config_change_in_progress:
type: boolean
description: Is the keyspace undergoing a config change
ready:
type: boolean
description: Is the keyspace provisioned and serving traffic
metal:
type: boolean
description: Is the keyspace running on metal instances
default:
type: boolean
description: Is this the default keyspace for the branch
imported:
type: boolean
description: Is this keyspace used in an import
vector_pool_allocation:
type: number
description: >-
Percentage of buffer pool memory allocated to vector
indexes
nullable: true
node_ttl_strategy:
type: string
enum:
- node_ttl_follow_maintenance
- node_ttl_always
- node_ttl_off
description: Controls when node TTL drains are allowed
replication_durability_constraints:
type: object
properties:
strategy:
type: string
enum:
- available
- lag
- always
description: The replication durability strategy
nullable: true
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_pending
- config_change_in_progress
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`read_branch`
post:
tags:
- Database branch keyspaces
operationId: create_keyspace
summary: Create a keyspace
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the keyspace
cluster_size:
type: string
description: >-
The database cluster size name (e.g., 'PS_10', 'PS_80'). Use
the 'List available cluster sizes' endpoint to get available
options for your organization.
/v1/organizations/:organization/cluster-size-skus
extra_replicas:
type: integer
description: >-
The number of additional replicas beyond the included
default
shards:
type: integer
description: 'The number of shards. Default: 1'
required:
- name
- cluster_size
responses:
'200':
description: Returns a created keyspace
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
config_change_in_progress:
type: boolean
description: Is the keyspace undergoing a config change
ready:
type: boolean
description: Is the keyspace provisioned and serving traffic
metal:
type: boolean
description: Is the keyspace running on metal instances
default:
type: boolean
description: Is this the default keyspace for the branch
imported:
type: boolean
description: Is this keyspace used in an import
vector_pool_allocation:
type: number
description: >-
Percentage of buffer pool memory allocated to vector
indexes
nullable: true
node_ttl_strategy:
type: string
enum:
- node_ttl_follow_maintenance
- node_ttl_always
- node_ttl_off
description: Controls when node TTL drains are allowed
replication_durability_constraints:
type: object
properties:
strategy:
type: string
enum:
- available
- lag
- always
description: The replication durability strategy
nullable: true
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_pending
- config_change_in_progress
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`create_branch`
/organizations/{organization}/databases/{database}/branches/{branch}/keyspaces/{keyspace}:
get:
tags:
- Database branch keyspaces
operationId: get_keyspace
summary: Get a keyspace
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
'200':
description: Returns information about a keyspace
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
config_change_in_progress:
type: boolean
description: Is the keyspace undergoing a config change
ready:
type: boolean
description: Is the keyspace provisioned and serving traffic
metal:
type: boolean
description: Is the keyspace running on metal instances
default:
type: boolean
description: Is this the default keyspace for the branch
imported:
type: boolean
description: Is this keyspace used in an import
vector_pool_allocation:
type: number
description: >-
Percentage of buffer pool memory allocated to vector
indexes
nullable: true
node_ttl_strategy:
type: string
enum:
- node_ttl_follow_maintenance
- node_ttl_always
- node_ttl_off
description: Controls when node TTL drains are allowed
replication_durability_constraints:
type: object
properties:
strategy:
type: string
enum:
- available
- lag
- always
description: The replication durability strategy
nullable: true
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_pending
- config_change_in_progress
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`read_branch`
patch:
tags:
- Database branch keyspaces
operationId: update_keyspace
summary: Configure keyspace settings
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
'200':
description: Returns the keyspace
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
config_change_in_progress:
type: boolean
description: Is the keyspace undergoing a config change
ready:
type: boolean
description: Is the keyspace provisioned and serving traffic
metal:
type: boolean
description: Is the keyspace running on metal instances
default:
type: boolean
description: Is this the default keyspace for the branch
imported:
type: boolean
description: Is this keyspace used in an import
vector_pool_allocation:
type: number
description: >-
Percentage of buffer pool memory allocated to vector
indexes
nullable: true
node_ttl_strategy:
type: string
enum:
- node_ttl_follow_maintenance
- node_ttl_always
- node_ttl_off
description: Controls when node TTL drains are allowed
replication_durability_constraints:
type: object
properties:
strategy:
type: string
enum:
- available
- lag
- always
description: The replication durability strategy
nullable: true
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_pending
- config_change_in_progress
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`create_branch`
delete:
tags:
- Database branch keyspaces
operationId: delete_keyspace
summary: Delete a keyspace
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
'204':
description: Delete a keyspace
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`delete_branch`, `delete_production_branch`
/organizations/{organization}/databases/{database}/branches/{branch}/keyspaces/{keyspace}/rollout-status:
get:
tags:
- Database branch keyspaces
operationId: get_keyspace_rollout_status
summary: Get keyspace rollout status
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
'200':
description: Returns information about a keyspace's rollout
headers: {}
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the keyspace
state:
type: string
description: The current state of the rollout at the keyspace level
shards:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the shard
last_rollout_started_at:
type: string
description: The time at which the rollout started
last_rollout_finished_at:
type: string
description: The time at which the rollout completed
state:
type: string
description: The current state of the rollout at the shard level
required:
- name
- last_rollout_started_at
- last_rollout_finished_at
- state
required:
- name
- state
- shards
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`read_branch`
/organizations/{organization}/databases/{database}/branches/{branch}/keyspaces/{keyspace}/vschema:
get:
tags:
- Keyspace VSchemas
operationId: get_keyspace_vschema
summary: Get the VSchema for the keyspace
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
'200':
description: Returns the VSchema for the keyspace
headers: {}
content:
application/json:
schema:
type: object
properties:
raw:
type: string
description: The keyspace's VSchema
required:
- raw
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
patch:
tags:
- Keyspace VSchemas
operationId: update_keyspace_vschema
summary: Update the VSchema for the keyspace
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
vschema:
type: string
description: The new VSchema for the keyspace
required:
- vschema
responses:
'200':
description: Returns the VSchema for the keyspace
headers: {}
content:
application/json:
schema:
type: object
properties:
raw:
type: string
description: The keyspace's VSchema
required:
- raw
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Content
'500':
description: Internal Server Error
description: >+
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`write_production_branch_vschema`, `write_branch_vschema`
/organizations/{organization}/databases/{database}/branches/{branch}/parameters:
get:
tags:
- Cluster parameters
operationId: list_parameters
summary: List cluster parameters
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
responses:
'200':
description: Returns cluster parameters
headers: {}
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
namespace:
type: string
enum:
- patroni
- pgconf
- pgbouncer
description: The namespace of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
extension:
type: boolean
description: Configures an extension
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- seconds
- select
- string
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
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
updated_at:
type: string
description: When the parameter was last updated
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
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options 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
- name
- display_name
- namespace
- category
- description
- extension
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >2-
Returns the parameters for a branch. To update the parameters, use the "Upsert a change request" endpoint.
### 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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/passwords:
get:
tags:
- Database branch passwords
operationId: list_passwords
summary: List passwords
parameters:
- name: organization
in: path
required: true
description: The name of the organization the password belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the password belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch the password belongs to
schema:
type: string
- name: read_only_region_id
in: query
description: >-
A read-only region of the database branch. If present, the password
results will be filtered to only those in the region
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns passwords for the branch
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: >-
List of IP addresses or CIDR ranges that can use
this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: >-
True if the credentials connect directly to a
vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: >-
The list of hosts in each availability zone
providing direct access to a vtgate
ttl_seconds:
type: integer
description: >-
Time to live (in seconds) for the password. The
password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
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
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
username:
type: string
description: The username for the password
plain_text:
type: string
description: >-
The plain text password. Null except in the response
from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
post:
tags:
- Database branch passwords
operationId: create_password
summary: Create a password
parameters:
- name: organization
in: path
required: true
description: The name of the organization the password belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the password belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch the password belongs to
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Optional name of the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The database role of the password (i.e. admin)
replica:
type: boolean
description: Whether the password is for a read replica
ttl:
type: integer
description: >-
Time to live (in seconds) for the password. The password
will be invalid when TTL has passed
cidrs:
type: array
items:
type: string
description: >-
List of IP addresses or CIDR ranges that can use this
password
direct_vtgate:
type: boolean
description: Whether the password connects directly to a VTGate
responses:
'201':
description: Returns the new credentials
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: >-
List of IP addresses or CIDR ranges that can use this
password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: >-
True if the credentials connect directly to a vtgate,
bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: >-
The list of hosts in each availability zone providing
direct access to a vtgate
ttl_seconds:
type: integer
description: >-
Time to live (in seconds) for the password. The password
will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
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
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
username:
type: string
description: The username for the password
plain_text:
type: string
description: >-
The plain text password. Null except in the response from
the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Content
'500':
description: Internal Server Error
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**
`connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/passwords/{id}:
get:
tags:
- Database branch passwords
operationId: get_password
summary: Get a password
parameters:
- name: organization
in: path
required: true
description: The name of the organization the password belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the password belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch the password belongs to
schema:
type: string
- name: id
in: path
required: true
description: The ID of the password
schema:
type: string
responses:
'200':
description: Returns a password
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: >-
List of IP addresses or CIDR ranges that can use this
password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: >-
True if the credentials connect directly to a vtgate,
bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: >-
The list of hosts in each availability zone providing
direct access to a vtgate
ttl_seconds:
type: integer
description: >-
Time to live (in seconds) for the password. The password
will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
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
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
username:
type: string
description: The username for the password
plain_text:
type: string
description: >-
The plain text password. Null except in the response from
the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
patch:
tags:
- Database branch passwords
operationId: update_password
summary: Update a password
parameters:
- name: organization
in: path
required: true
description: The name of the organization the password belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the password belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch the password belongs to
schema:
type: string
- name: id
in: path
required: true
description: The ID of the password
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name for the password
cidrs:
type: array
items:
type: string
description: >-
List of IP addresses or CIDR ranges that can use this
password
responses:
'200':
description: Returns the updated password
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: >-
List of IP addresses or CIDR ranges that can use this
password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: >-
True if the credentials connect directly to a vtgate,
bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: >-
The list of hosts in each availability zone providing
direct access to a vtgate
ttl_seconds:
type: integer
description: >-
Time to live (in seconds) for the password. The password
will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
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
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
username:
type: string
description: The username for the password
plain_text:
type: string
description: >-
The plain text password. Null except in the response from
the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
delete:
tags:
- Database branch passwords
operationId: delete_password
summary: Delete a password
parameters:
- name: organization
in: path
required: true
description: The name of the organization the password belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the password belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch the password belongs to
schema:
type: string
- name: id
in: path
required: true
description: The ID of the password
schema:
type: string
responses:
'204':
description: Deletes the password
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`delete_production_branch_password`, `delete_production_read_only_branch_password`, `delete_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/passwords/{id}/renew:
post:
tags:
- Database branch passwords
operationId: renew_password
summary: Renew a password
parameters:
- name: organization
in: path
required: true
description: The name of the organization the password belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the password belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch the password belongs to
schema:
type: string
- name: id
in: path
required: true
description: The ID of the password
schema:
type: string
responses:
'200':
description: Returns the renewed password
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: >-
List of IP addresses or CIDR ranges that can use this
password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: >-
True if the credentials connect directly to a vtgate,
bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: >-
The list of hosts in each availability zone providing
direct access to a vtgate
ttl_seconds:
type: integer
description: >-
Time to live (in seconds) for the password. The password
will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
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
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
username:
type: string
description: The username for the password
plain_text:
type: string
description: >-
The plain text password. Null except in the response from
the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/promote:
post:
tags:
- Database branches
operationId: promote_branch
summary: Promote a 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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
'200':
description: Returns a production 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
description: >-
Promotes a branch from development to production
### 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**
`connect_production_branch`, `promote_branches`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `promote_branches` |
| Database | `promote_branches` |
/organizations/{organization}/databases/{database}/branches/{branch}/query-patterns:
get:
tags:
- Query Insights reports
operationId: list_generated_query_patterns_reports
summary: List generated query patterns reports
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: starting_after
in: query
description: If provided, returns results after the specified cursor
schema:
type: string
- name: ending_before
in: query
description: If provided, returns results before the specified cursor
schema:
type: string
- name: limit
in: query
description: If provided, specifies the number of returned results (max 100)
schema:
type: integer
default: 25
responses:
'200':
description: Returns the generated query patterns reports
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
has_next:
type: boolean
description: Whether there is a next page of results
has_prev:
type: boolean
description: Whether there is a previous page of results
cursor_start:
type: string
description: >-
The ID of the first object in the current results, or null
when there are no results
nullable: true
cursor_end:
type: string
description: >-
The ID of the last object in the current results, or null
when there are no results
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
nullable: true
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
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
- state
- created_at
- finished_at
- url
- download_url
- actor
required:
- type
- has_next
- has_prev
- cursor_start
- cursor_end
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
post:
tags:
- Query Insights reports
operationId: create_query_patterns_report
summary: Create a new query patterns report
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
'201':
description: The created query patterns download
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
nullable: true
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
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
- state
- created_at
- finished_at
- url
- download_url
- actor
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/query-patterns/{id}:
get:
tags:
- Query Insights reports
operationId: get_query_patterns_report_status
summary: Show the status of a query patterns report
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: id
in: path
required: true
description: The ID of the query patterns report
schema:
type: string
responses:
'200':
description: The retrieved query patterns download
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
nullable: true
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
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
- state
- created_at
- finished_at
- url
- download_url
- actor
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
delete:
tags:
- Query Insights reports
operationId: delete_query_patterns_report
summary: Delete a query patterns report
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: id
in: path
required: true
description: The ID of the query patterns report
schema:
type: string
responses:
'204':
description: Delete a query patterns report
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/query-patterns/{id}/download:
get:
tags:
- Query Insights reports
operationId: get_query_patterns_report
summary: Download a finished query patterns report
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: id
in: path
required: true
description: The ID of the query patterns report
schema:
type: string
responses:
'302':
description: Redirect to the query patterns download
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
nullable: true
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
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
- state
- created_at
- finished_at
- url
- download_url
- actor
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/resizes:
delete:
tags:
- Branch changes
operationId: cancel_branch_change_request
summary: Cancel a change request
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
responses:
'204':
description: Cancels a change request
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles:
get:
tags:
- Roles
operationId: list_roles
summary: List roles
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
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns roles
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: >-
The database connection string for private
connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
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
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
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
post:
tags:
- Roles
operationId: create_role
summary: Create role credentials
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 name of the role
ttl:
type: integer
description: Time to live in seconds
inherited_roles:
type: array
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
description: Roles to inherit from
require_where_on_delete:
type: string
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
description: Require WHERE clause on UPDATE statements
responses:
'200':
description: Returns the new credentials
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
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
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
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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_production_branch_password`, `create_production_read_only_branch_password`, `create_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/default:
get:
tags:
- Roles
operationId: get_default_role
summary: Get the default postgres role
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
responses:
'200':
description: Returns the default postgres role
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
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
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
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/reset-default:
post:
tags:
- Roles
operationId: reset_default_role
summary: Reset default credentials
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
responses:
'200':
description: Returns the new credentials
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
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
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
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`delete_production_branch_password`, `delete_production_read_only_branch_password`, `delete_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/{id}:
get:
tags:
- Roles
operationId: get_role
summary: Get a role
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
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
responses:
'200':
description: Returns a role
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
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
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
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
patch:
tags:
- Roles
operationId: update_role
summary: Update role name
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
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The new name of the role
require_where_on_delete:
type: string
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
description: Require WHERE clause on UPDATE statements
responses:
'200':
description: Returns the updated role
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
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
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
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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_production_branch_password`, `create_production_read_only_branch_password`, `create_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
delete:
tags:
- Roles
operationId: delete_role
summary: Delete role credentials
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
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
- name: successor
in: query
description: The optional role to reassign ownership to before dropping
schema:
type: string
responses:
'204':
description: Deletes the role credentials
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`delete_production_branch_password`, `delete_production_read_only_branch_password`, `delete_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/{id}/reassign:
post:
tags:
- Roles
operationId: reassign_role_objects
summary: Reassign objects owned by one role to another role
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
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
successor:
type: string
description: The role to reassign ownership to
required:
- successor
responses:
'204':
description: Objects reassigned successfully
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`delete_production_branch_password`, `delete_production_read_only_branch_password`, `delete_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/{id}/renew:
post:
tags:
- Roles
operationId: renew_role
summary: Renew role expiration
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
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
responses:
'200':
description: Returns the renewed role
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
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
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
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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_production_branch_password`, `create_production_read_only_branch_password`, `create_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/{id}/reset:
post:
tags:
- Roles
operationId: reset_role
summary: Reset a role's password
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
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
responses:
'200':
description: Returns the role with new password
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
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
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
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`delete_production_branch_password`, `delete_production_read_only_branch_password`, `delete_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`,
`manage_production_branch_passwords`, `manage_read_only_passwords`,
`manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`,
`manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/safe-migrations:
post:
tags:
- Database branches
operationId: enable_safe_migrations
summary: Enable safe migrations for a 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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
'200':
description: Returns the branch with safe migrations enabled
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
description: |+
delete:
tags:
- Database branches
operationId: disable_safe_migrations
summary: Disable safe migrations for a 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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
'200':
description: Returns the branch with safe migrations disabled
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
description: |+
/organizations/{organization}/databases/{database}/branches/{branch}/schema:
get:
tags:
- Database branches
operationId: get_branch_schema
summary: Get a branch schema
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: query
description: Return the schema for a single Vitess keyspace
schema:
type: string
- name: namespace
in: query
description: >-
Return the schema for a PostgreSQL catalog namespace in
`.` format (e.g. public.schema1)
schema:
type: string
responses:
'200':
description: Gets the schema for the branch
headers: {}
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
name:
type: string
description: Name of the table
html:
type: string
description: Syntax highlighted HTML for the table's schema
raw:
type: string
description: The table's schema
required:
- name
- html
- raw
required:
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/schema/lint:
get:
tags:
- Database branches
operationId: lint_branch_schema
summary: Lint a branch schema
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
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns a list of schema errors for a branch
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
lint_error:
type: string
description: Code representing the type of error
subject_type:
type: string
enum:
- table
- vschema
- routing_rules
description: The subject for the errors
keyspace_name:
type: string
description: The keyspace of the schema with the error
table_name:
type: string
description: The table with the error
error_description:
type: string
description: A description for the error that occurred
docs_url:
type: string
description: A link to the documentation related to the error
column_name:
type: string
description: The column in a table relevant to the error
foreign_key_column_names:
items:
type: string
type: array
description: A list of invalid foreign key columns in a table
auto_increment_column_names:
items:
type: string
type: array
description: A list of invalid auto-incremented columns
charset_name:
type: string
description: The charset of the schema
engine_name:
type: string
description: The engine of the schema
vindex_name:
type: string
description: The name of the vindex for the schema
json_path:
type: string
description: The path for an invalid JSON column
check_constraint_name:
type: string
description: The name of the invalid check constraint
enum_value:
type: string
description: The name of the invalid enum value
partitioning_type:
type: string
description: The name of the invalid partitioning type
partition_name:
type: string
description: The name of the invalid partition in the schema
required:
- lint_error
- subject_type
- keyspace_name
- table_name
- error_description
- docs_url
- column_name
- foreign_key_column_names
- auto_increment_column_names
- charset_name
- engine_name
- vindex_name
- json_path
- check_constraint_name
- enum_value
- partitioning_type
- partition_name
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/traffic/budgets:
get:
tags:
- Traffic budgets
operationId: list_traffic_budgets
summary: List traffic budgets
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
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
- name: period
in: query
description: Time period filter (e.g., '1h', '24h', '7d')
schema:
type: string
- name: created_at
in: query
description: 'Filter by creation date range (format: ''start..end'')'
schema:
type: string
- name: fingerprint
in: query
description: Filter budgets by query fingerprint
schema:
type: string
responses:
'200':
description: Returns the traffic budgets for the branch
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic budget
name:
type: string
description: The name of the budget
mode:
type: string
enum:
- enforce
- warn
- 'off'
description: The mode of the budget
capacity:
type: number
description: >-
The maximum capacity that can be banked, measured as
a percentage of seconds of full server usage
(0-6000). Unlimited when not set.
nullable: true
rate:
type: number
description: >-
The rate at which capacity refills, as a percentage
of server resources (0-100). Unlimited when not set.
nullable: true
burst:
type: number
description: >-
The maximum capacity a single query can consume,
measured as a percentage of seconds of full server
usage (0-6000). Unlimited when not set.
nullable: true
concurrency:
type: number
description: >-
The percentage of available worker processes this
policy can use (0-100). Unlimited when not set.
nullable: true
warning_threshold:
type: number
description: >-
A percentage of capacity, burst, or concurrency
thresholds to emit warnings for enforced budgets
(0-100).
nullable: true
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
rules:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
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
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
created_at:
type: string
description: When the budget was created
updated_at:
type: string
description: When the budget was updated
required:
- id
- name
- mode
- actor
- rules
- created_at
- updated_at
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
post:
tags:
- Traffic budgets
operationId: create_traffic_budget
summary: Create a traffic budget
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: Name of the traffic budget
mode:
type: string
enum:
- enforce
- warn
- 'off'
description: The mode of the traffic budget
capacity:
type: integer
description: >-
The maximum capacity that can be banked, measured as a
percentage of seconds of full server usage (0-6000).
Unlimited when not set.
rate:
type: integer
description: >-
The rate at which capacity refills, as a percentage of
server resources (0-100). Unlimited when not set.
burst:
type: integer
description: >-
The maximum capacity a single query can consume, measured as
a percentage of seconds of full server usage (0-6000).
Unlimited when not set.
concurrency:
type: integer
description: >-
The percentage of available worker processes this policy can
use (0-100). Unlimited when not set.
warning_threshold:
type: integer
description: >-
A percentage of capacity, burst, or concurrency thresholds
to emit warnings for enforced budgets (0-100).
rules:
type: array
items:
type: string
description: Array of traffic rules to apply to the budget
responses:
'201':
description: Returns the created traffic budget
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the traffic budget
name:
type: string
description: The name of the budget
mode:
type: string
enum:
- enforce
- warn
- 'off'
description: The mode of the budget
capacity:
type: number
description: >-
The maximum capacity that can be banked, measured as a
percentage of seconds of full server usage (0-6000).
Unlimited when not set.
nullable: true
rate:
type: number
description: >-
The rate at which capacity refills, as a percentage of
server resources (0-100). Unlimited when not set.
nullable: true
burst:
type: number
description: >-
The maximum capacity a single query can consume, measured
as a percentage of seconds of full server usage (0-6000).
Unlimited when not set.
nullable: true
concurrency:
type: number
description: >-
The percentage of available worker processes this policy
can use (0-100). Unlimited when not set.
nullable: true
warning_threshold:
type: number
description: >-
A percentage of capacity, burst, or concurrency thresholds
to emit warnings for enforced budgets (0-100).
nullable: true
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
rules:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
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
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
created_at:
type: string
description: When the budget was created
updated_at:
type: string
description: When the budget was updated
required:
- id
- name
- mode
- actor
- rules
- created_at
- updated_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_branches` |
| Database | `write_branches` |
| Branch | `write_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/traffic/budgets/{budget_id}/rules:
post:
tags:
- Traffic rules
operationId: create_traffic_rule
summary: Create a traffic rule
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
- name: budget_id
in: path
required: true
description: The ID of the traffic budget
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
kind:
type: string
enum:
- match
description: Kind of rule
keyspace:
type: string
description: The keyspace to apply a query pattern rule to
fingerprint:
type: string
description: Query pattern fingerprint to apply rule to
tags:
type: array
items:
type: string
description: Optional array of tags for this rule
responses:
'201':
description: Returns the created traffic rule
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
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
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_branches` |
| Database | `write_branches` |
| Branch | `write_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/traffic/budgets/{budget_id}/rules/{id}:
delete:
tags:
- Traffic rules
operationId: delete_traffic_rule
summary: Delete a traffic rule
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
- name: budget_id
in: path
required: true
description: The ID of the traffic budget
schema:
type: string
- name: id
in: path
required: true
description: The ID of the traffic rule
schema:
type: string
responses:
'204':
description: Traffic rule successfully deleted
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`delete_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `delete_branches`, `delete_production_branches` |
| Database | `delete_branches`, `delete_production_branches` |
| Branch | `delete_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/traffic/budgets/{id}:
get:
tags:
- Traffic budgets
operationId: get_traffic_budget
summary: Get a traffic budget
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
- name: id
in: path
required: true
description: The ID of the traffic budget
schema:
type: string
responses:
'200':
description: Returns the traffic budget
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the traffic budget
name:
type: string
description: The name of the budget
mode:
type: string
enum:
- enforce
- warn
- 'off'
description: The mode of the budget
capacity:
type: number
description: >-
The maximum capacity that can be banked, measured as a
percentage of seconds of full server usage (0-6000).
Unlimited when not set.
nullable: true
rate:
type: number
description: >-
The rate at which capacity refills, as a percentage of
server resources (0-100). Unlimited when not set.
nullable: true
burst:
type: number
description: >-
The maximum capacity a single query can consume, measured
as a percentage of seconds of full server usage (0-6000).
Unlimited when not set.
nullable: true
concurrency:
type: number
description: >-
The percentage of available worker processes this policy
can use (0-100). Unlimited when not set.
nullable: true
warning_threshold:
type: number
description: >-
A percentage of capacity, burst, or concurrency thresholds
to emit warnings for enforced budgets (0-100).
nullable: true
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
rules:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
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
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
created_at:
type: string
description: When the budget was created
updated_at:
type: string
description: When the budget was updated
required:
- id
- name
- mode
- actor
- rules
- created_at
- updated_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
patch:
tags:
- Traffic budgets
operationId: update_traffic_budget
summary: Update a traffic budget
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
- name: id
in: path
required: true
description: The ID of the traffic budget
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the traffic budget
mode:
type: string
enum:
- enforce
- warn
- 'off'
description: The mode of the traffic budget
capacity:
type: integer
description: >-
The maximum capacity that can be banked, measured as a
percentage of seconds of full server usage (0-6000).
Unlimited when not set.
rate:
type: integer
description: >-
The rate at which capacity refills, as a percentage of
server resources (0-100). Unlimited when not set.
burst:
type: integer
description: >-
The maximum capacity a single query can consume, measured as
a percentage of seconds of full server usage (0-6000).
Unlimited when not set.
concurrency:
type: integer
description: >-
The percentage of available worker processes this policy can
use (0-100). Unlimited when not set.
warning_threshold:
type: integer
description: >-
A percentage of capacity, burst, or concurrency thresholds
to emit warnings for enforced budgets (0-100).
rules:
type: array
items:
type: string
description: Array of traffic rules to apply to the budget
responses:
'200':
description: Returns the updated traffic budget
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the traffic budget
name:
type: string
description: The name of the budget
mode:
type: string
enum:
- enforce
- warn
- 'off'
description: The mode of the budget
capacity:
type: number
description: >-
The maximum capacity that can be banked, measured as a
percentage of seconds of full server usage (0-6000).
Unlimited when not set.
nullable: true
rate:
type: number
description: >-
The rate at which capacity refills, as a percentage of
server resources (0-100). Unlimited when not set.
nullable: true
burst:
type: number
description: >-
The maximum capacity a single query can consume, measured
as a percentage of seconds of full server usage (0-6000).
Unlimited when not set.
nullable: true
concurrency:
type: number
description: >-
The percentage of available worker processes this policy
can use (0-100). Unlimited when not set.
nullable: true
warning_threshold:
type: number
description: >-
A percentage of capacity, burst, or concurrency thresholds
to emit warnings for enforced budgets (0-100).
nullable: true
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
rules:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
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
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
created_at:
type: string
description: When the budget was created
updated_at:
type: string
description: When the budget was updated
required:
- id
- name
- mode
- actor
- rules
- created_at
- updated_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_branches` |
| Database | `write_branches` |
| Branch | `write_branch` |
delete:
tags:
- Traffic budgets
operationId: delete_traffic_budget
summary: Delete a traffic budget
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
- name: id
in: path
required: true
description: The ID of the traffic budget
schema:
type: string
responses:
'204':
description: Traffic budget successfully deleted
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`delete_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `delete_branches`, `delete_production_branches` |
| Database | `delete_branches`, `delete_production_branches` |
| Branch | `delete_branch` |
/organizations/{organization}/databases/{database}/cidrs:
get:
tags:
- Database Postgres IP restrictions
operationId: list_database_postgres_cidrs
summary: List IP restriction entries
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns IP restriction entries for the database
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
nullable: true
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
- schema
- role
- cidrs
- created_at
- updated_at
- deleted_at
- actor
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity - Invalid parameters or validation errors
'500':
description: Internal Server Error
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**
`read_database`, `read_databases`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
post:
tags:
- Database Postgres IP restrictions
operationId: create_database_postgres_cidr
summary: Create an IP restriction entry
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
schema:
type: string
description: >-
The PostgreSQL schema to restrict access to. Leave empty or
omit to allow access to all schemas.
role:
type: string
description: >-
The PostgreSQL role to restrict access to. Leave empty or
omit to allow access for all roles.
cidrs:
type: array
items:
type: string
description: >-
List of IPv4 CIDR ranges (e.g., ['192.168.1.0/24',
'192.168.1.1/32']). Must contain at least one valid IPv4
address or range.
required:
- cidrs
responses:
'201':
description: Returns the created IP restriction entry
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
nullable: true
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
- schema
- role
- cidrs
- created_at
- updated_at
- deleted_at
- actor
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity - Invalid parameters or validation errors
'500':
description: Internal Server Error
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` |
/organizations/{organization}/databases/{database}/cidrs/{id}:
get:
tags:
- Database Postgres IP restrictions
operationId: get_database_postgres_cidr
summary: Get an IP restriction entry
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the IP restriction entry
schema:
type: string
responses:
'200':
description: Returns an IP restriction entry
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
nullable: true
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
- schema
- role
- cidrs
- created_at
- updated_at
- deleted_at
- actor
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity - Invalid parameters or validation errors
'500':
description: Internal Server Error
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**
`read_database`, `read_databases`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
patch:
tags:
- Database Postgres IP restrictions
operationId: update_database_postgres_cidr
summary: Update an IP restriction entry
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the IP restriction entry
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
schema:
type: string
description: >-
The PostgreSQL schema to restrict access to. Leave empty to
allow access to all schemas.
role:
type: string
description: >-
The PostgreSQL role to restrict access to. Leave empty to
allow access for all roles.
cidrs:
type: array
items:
type: string
description: >-
List of IPv4 CIDR ranges (e.g., ['192.168.1.0/24',
'192.168.1.1/32']). Only provided fields will be updated.
responses:
'200':
description: Returns the updated IP restriction entry
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
nullable: true
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
- schema
- role
- cidrs
- created_at
- updated_at
- deleted_at
- actor
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity - Invalid parameters or validation errors
'500':
description: Internal Server Error
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` |
delete:
tags:
- Database Postgres IP restrictions
operationId: delete_database_postgres_cidr
summary: Delete an IP restriction entry
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the IP restriction entry
schema:
type: string
responses:
'204':
description: >-
IP restriction entry deleted successfully. Note: This will also
remove the restriction from all database branches.
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity - Invalid parameters or validation errors
'500':
description: Internal Server Error
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` |
/organizations/{organization}/databases/{database}/deploy-queue:
get:
tags:
- Deploy requests
operationId: get_deploy_queue
summary: Get the deploy queue
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns the deploy queue for a database
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once
deployment is finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head
branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: >-
Whether or not the deployment cutover will expire
soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will be
merged into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with
this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy
error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable
of dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the
deploy operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the
deploy operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy
operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this
operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: >-
The DDL statement for the deploy operation
summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy operation
summary
operation_name:
type: string
description: >-
The operation name of the deploy operation
summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy
operation summary was last used
nullable: true
throttled_at:
type: string
description: >-
When the deploy operation summary was last
throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this
operation summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified
by the deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by
the deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is
capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the
deploy operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the
deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion
for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment from
completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in this
deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: >-
The name of the table that is locked by the
deployment.
nullable: true
instant_ddl:
type: boolean
description: >-
Whether or not the deployment is an instant DDL
deployment
instant_ddl_eligible:
type: boolean
description: >-
Whether or not the deployment is eligible for
instant DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is
currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is paused,
if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >
The deploy queue returns the current list of deploy requests in the
order they will be deployed.
/organizations/{organization}/databases/{database}/deploy-requests:
get:
tags:
- Deploy requests
operationId: list_deploy_requests
summary: List deploy requests
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: state
in: query
description: Filter by state of the deploy request (open, closed, deployed)
schema:
type: string
- name: branch
in: query
description: Filter by the name of the branch the deploy request is created from
schema:
type: string
- name: into_branch
in: query
description: >-
Filter by the name of the branch the deploy request will be merged
into
schema:
type: string
- name: deployed_at
in: query
description: >-
Filter deploy requests by the date they were deployed. (e.g.
2023-01-01T00:00:00Z..2023-01-31T23:59:59Z)
schema:
type: string
- name: running_at
in: query
description: >-
Filter deploy requests by the date they were running. (e.g.
2023-01-01T00:00:00Z..2023-01-31T23:59:59Z)
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns a list of deploy requests
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
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
closed_by:
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
branch:
type: string
description: >-
The name of the branch the deploy request was
created from
branch_id:
type: string
description: >-
The ID of the branch the deploy request was created
from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
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
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: >-
The name of the branch the deploy request will be
merged into
into_branch_sharded:
type: boolean
description: >-
Whether or not the branch the deploy request will be
merged into is sharded
into_branch_shard_count:
type: integer
description: >-
The number of shards the branch the deploy request
will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once
deployment is finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head
branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: >-
When the cutover for the deployment was
initiated
nullable: true
cutover_expiring:
type: boolean
description: >-
Whether or not the deployment cutover will
expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will
be merged into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with
this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy
operation
table_name:
type: string
description: >-
The name of the table modifed by the
deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for
the deploy operation
nullable: true
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the
deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: >-
When the deploy operation was last
throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is
capable of dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the
deploy operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the
deploy operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy
operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this
operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: >-
When the deploy operation summary was
created
deploy_errors:
type: string
description: >-
Deploy errors for the deploy operation
summary
ddl_statement:
type: string
description: >-
The DDL statement for the deploy operation
summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for
the deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy
operation summary
operation_name:
type: string
description: >-
The operation name of the deploy operation
summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation summary
table_name:
type: string
description: >-
The name of the table modifed by the
deploy operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy
operation summary was last used
nullable: true
throttled_at:
type: string
description: >-
When the deploy operation summary was last
throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this
operation summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace
modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified
by the deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation
summary is capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the
deploy operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by
the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion
for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment
from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in
this deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: >-
When the schema was last updated for the
deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: >-
The name of the table that is locked by the
deployment.
nullable: true
instant_ddl:
type: boolean
description: >-
Whether or not the deployment is an instant DDL
deployment
instant_ddl_eligible:
type: boolean
description: >-
Whether or not the deployment is eligible for
instant DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch
is currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is
paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
List deploy requests for a database
### 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**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
post:
tags:
- Deploy requests
operationId: create_deploy_request
summary: Create a deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
branch:
type: string
description: The name of the branch the deploy request is created from
into_branch:
type: string
description: >-
The name of the branch the deploy request will be merged
into
notes:
type: string
description: Notes about the deploy request
auto_cutover:
type: boolean
description: >-
Whether or not to enable auto_cutover for the deploy
request. When enabled, will auto cutover to the new schema
as soon as it is ready.
auto_delete_branch:
type: boolean
description: >-
Whether or not to enable auto_delete_branch for the deploy
request. When enabled, will delete the branch once the DR
successfully completes.
required:
- branch
- into_branch
responses:
'201':
description: Returns the created deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
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
closed_by:
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
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
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
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: >-
The name of the branch the deploy request will be merged
into
into_branch_sharded:
type: boolean
description: >-
Whether or not the branch the deploy request will be
merged into is sharded
into_branch_shard_count:
type: integer
description: >-
The number of shards the branch the deploy request will be
merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once
deployment is finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch
once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will be
merged into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with this
deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy
error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable
of dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: >-
The DDL statement for the deploy operation
summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy operation
summary
operation_name:
type: string
description: >-
The operation name of the deploy operation
summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy operation
summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
summary was last used
nullable: true
throttled_at:
type: string
description: >-
When the deploy operation summary was last
throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this operation
summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by
the deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the
deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is
capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the
deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for
the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment from
completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in this
deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: >-
The name of the table that is locked by the
deployment.
nullable: true
instant_ddl:
type: boolean
description: >-
Whether or not the deployment is an instant DDL
deployment
instant_ddl_eligible:
type: boolean
description: >-
Whether or not the deployment is eligible for instant
DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is
currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is paused, if
known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_deploy_request`, `create_deploy_requests`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_deploy_requests` |
| Database | `write_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}:
get:
tags:
- Deploy requests
operationId: get_deploy_request
summary: Get a deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
'200':
description: Returns information about a deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
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
closed_by:
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
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
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
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: >-
The name of the branch the deploy request will be merged
into
into_branch_sharded:
type: boolean
description: >-
Whether or not the branch the deploy request will be
merged into is sharded
into_branch_shard_count:
type: integer
description: >-
The number of shards the branch the deploy request will be
merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once
deployment is finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch
once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will be
merged into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with this
deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy
error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable
of dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: >-
The DDL statement for the deploy operation
summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy operation
summary
operation_name:
type: string
description: >-
The operation name of the deploy operation
summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy operation
summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
summary was last used
nullable: true
throttled_at:
type: string
description: >-
When the deploy operation summary was last
throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this operation
summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by
the deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the
deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is
capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the
deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for
the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment from
completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in this
deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: >-
The name of the table that is locked by the
deployment.
nullable: true
instant_ddl:
type: boolean
description: >-
Whether or not the deployment is an instant DDL
deployment
instant_ddl_eligible:
type: boolean
description: >-
Whether or not the deployment is eligible for instant
DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is
currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is paused, if
known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
patch:
tags:
- Deploy requests
operationId: close_deploy_request
summary: Close a deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
state:
type: string
enum:
- closed
description: The deploy request will be updated to this state
responses:
'200':
description: Returns the updated deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
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
closed_by:
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
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
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
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: >-
The name of the branch the deploy request will be merged
into
into_branch_sharded:
type: boolean
description: >-
Whether or not the branch the deploy request will be
merged into is sharded
into_branch_shard_count:
type: integer
description: >-
The number of shards the branch the deploy request will be
merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once
deployment is finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch
once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will be
merged into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with this
deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy
error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable
of dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: >-
The DDL statement for the deploy operation
summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy operation
summary
operation_name:
type: string
description: >-
The operation name of the deploy operation
summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy operation
summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
summary was last used
nullable: true
throttled_at:
type: string
description: >-
When the deploy operation summary was last
throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this operation
summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by
the deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the
deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is
capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the
deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for
the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment from
completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in this
deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: >-
The name of the table that is locked by the
deployment.
nullable: true
instant_ddl:
type: boolean
description: >-
Whether or not the deployment is an instant DDL
deployment
instant_ddl_eligible:
type: boolean
description: >-
Whether or not the deployment is eligible for instant
DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is
currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is paused, if
known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_deploy_requests` |
| Database | `write_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/apply-deploy:
post:
tags:
- Deploy requests
operationId: complete_gated_deploy_request
summary: Complete a gated deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
'200':
description: Returns the deploy request whose deployment has been completed
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
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
closed_by:
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
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
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
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: >-
The name of the branch the deploy request will be merged
into
into_branch_sharded:
type: boolean
description: >-
Whether or not the branch the deploy request will be
merged into is sharded
into_branch_shard_count:
type: integer
description: >-
The number of shards the branch the deploy request will be
merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once
deployment is finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch
once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will be
merged into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with this
deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy
error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable
of dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: >-
The DDL statement for the deploy operation
summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy operation
summary
operation_name:
type: string
description: >-
The operation name of the deploy operation
summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy operation
summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
summary was last used
nullable: true
throttled_at:
type: string
description: >-
When the deploy operation summary was last
throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this operation
summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by
the deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the
deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is
capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the
deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for
the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment from
completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in this
deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: >-
The name of the table that is locked by the
deployment.
nullable: true
instant_ddl:
type: boolean
description: >-
Whether or not the deployment is an instant DDL
deployment
instant_ddl_eligible:
type: boolean
description: >-
Whether or not the deployment is eligible for instant
DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is
currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is paused, if
known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/auto-apply:
put:
tags:
- Deploy requests
operationId: update_auto_apply
summary: Update auto-apply for deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
enable:
type: boolean
description: Whether or not to enable auto-apply for the deploy request
responses:
'200':
description: Returns the deploy request whose auto-apply setting was updated
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
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
closed_by:
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
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
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
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: >-
The name of the branch the deploy request will be merged
into
into_branch_sharded:
type: boolean
description: >-
Whether or not the branch the deploy request will be
merged into is sharded
into_branch_shard_count:
type: integer
description: >-
The number of shards the branch the deploy request will be
merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once
deployment is finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch
once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will be
merged into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with this
deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy
error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable
of dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: >-
The DDL statement for the deploy operation
summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy operation
summary
operation_name:
type: string
description: >-
The operation name of the deploy operation
summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy operation
summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
summary was last used
nullable: true
throttled_at:
type: string
description: >-
When the deploy operation summary was last
throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this operation
summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by
the deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the
deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is
capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the
deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for
the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment from
completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in this
deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: >-
The name of the table that is locked by the
deployment.
nullable: true
instant_ddl:
type: boolean
description: >-
Whether or not the deployment is an instant DDL
deployment
instant_ddl_eligible:
type: boolean
description: >-
Whether or not the deployment is eligible for instant
DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is
currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is paused, if
known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
Enables or disabled the auto-apply setting for a deploy request
### 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**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/auto-delete-branch:
put:
tags:
- Deploy requests
operationId: update_auto_delete_branch
summary: Update auto-delete branch for deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
enable:
type: boolean
description: >-
Whether or not to enable auto-delete branch for the deploy
request
responses:
'200':
description: >-
Returns the deploy request whose auto-delete branch setting was
updated
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
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
closed_by:
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
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
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
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: >-
The name of the branch the deploy request will be merged
into
into_branch_sharded:
type: boolean
description: >-
Whether or not the branch the deploy request will be
merged into is sharded
into_branch_shard_count:
type: integer
description: >-
The number of shards the branch the deploy request will be
merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once
deployment is finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch
once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will be
merged into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with this
deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy
error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable
of dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: >-
The DDL statement for the deploy operation
summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy operation
summary
operation_name:
type: string
description: >-
The operation name of the deploy operation
summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy operation
summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
summary was last used
nullable: true
throttled_at:
type: string
description: >-
When the deploy operation summary was last
throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this operation
summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by
the deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the
deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is
capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the
deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for
the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment from
completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in this
deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: >-
The name of the table that is locked by the
deployment.
nullable: true
instant_ddl:
type: boolean
description: >-
Whether or not the deployment is an instant DDL
deployment
instant_ddl_eligible:
type: boolean
description: >-
Whether or not the deployment is eligible for instant
DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is
currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is paused, if
known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
Enables or disabled the auto-delete branch setting for a deploy request
### 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**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/cancel:
post:
tags:
- Deploy requests
operationId: cancel_deploy_request
summary: Cancel a queued deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
'200':
description: Returns the deploy request whose deployment was canceled
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
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
closed_by:
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
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
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
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: >-
The name of the branch the deploy request will be merged
into
into_branch_sharded:
type: boolean
description: >-
Whether or not the branch the deploy request will be
merged into is sharded
into_branch_shard_count:
type: integer
description: >-
The number of shards the branch the deploy request will be
merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once
deployment is finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch
once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will be
merged into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with this
deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy
error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable
of dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: >-
The DDL statement for the deploy operation
summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy operation
summary
operation_name:
type: string
description: >-
The operation name of the deploy operation
summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy operation
summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
summary was last used
nullable: true
throttled_at:
type: string
description: >-
When the deploy operation summary was last
throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this operation
summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by
the deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the
deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is
capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the
deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for
the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment from
completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in this
deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: >-
The name of the table that is locked by the
deployment.
nullable: true
instant_ddl:
type: boolean
description: >-
Whether or not the deployment is an instant DDL
deployment
instant_ddl_eligible:
type: boolean
description: >-
Whether or not the deployment is eligible for instant
DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is
currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is paused, if
known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/complete-deploy:
post:
tags:
- Deploy requests
operationId: complete_errored_deploy
summary: Complete an errored deploy
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
'200':
description: Returns the completed deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
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
closed_by:
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
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
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
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: >-
The name of the branch the deploy request will be merged
into
into_branch_sharded:
type: boolean
description: >-
Whether or not the branch the deploy request will be
merged into is sharded
into_branch_shard_count:
type: integer
description: >-
The number of shards the branch the deploy request will be
merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once
deployment is finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch
once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will be
merged into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with this
deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy
error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable
of dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: >-
The DDL statement for the deploy operation
summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy operation
summary
operation_name:
type: string
description: >-
The operation name of the deploy operation
summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy operation
summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
summary was last used
nullable: true
throttled_at:
type: string
description: >-
When the deploy operation summary was last
throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this operation
summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by
the deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the
deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is
capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the
deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for
the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment from
completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in this
deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: >-
The name of the table that is locked by the
deployment.
nullable: true
instant_ddl:
type: boolean
description: >-
Whether or not the deployment is an instant DDL
deployment
instant_ddl_eligible:
type: boolean
description: >-
Whether or not the deployment is eligible for instant
DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is
currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is paused, if
known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/deploy:
post:
tags:
- Deploy requests
operationId: queue_deploy_request
summary: Queue a deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
instant_ddl:
type: boolean
description: >-
Whether or not to deploy the request with instant DDL.
Defaults to false.
responses:
'200':
description: Returns the deployed deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
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
closed_by:
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
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
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
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: >-
The name of the branch the deploy request will be merged
into
into_branch_sharded:
type: boolean
description: >-
Whether or not the branch the deploy request will be
merged into is sharded
into_branch_shard_count:
type: integer
description: >-
The number of shards the branch the deploy request will be
merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once
deployment is finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch
once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will be
merged into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with this
deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy
error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable
of dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: >-
The DDL statement for the deploy operation
summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy operation
summary
operation_name:
type: string
description: >-
The operation name of the deploy operation
summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy operation
summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
summary was last used
nullable: true
throttled_at:
type: string
description: >-
When the deploy operation summary was last
throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this operation
summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by
the deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the
deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is
capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the
deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for
the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment from
completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in this
deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: >-
The name of the table that is locked by the
deployment.
nullable: true
instant_ddl:
type: boolean
description: >-
Whether or not the deployment is an instant DDL
deployment
instant_ddl_eligible:
type: boolean
description: >-
Whether or not the deployment is eligible for instant
DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is
currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is paused, if
known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/deployment:
get:
tags:
- Deploy requests
operationId: get_deployment
summary: Get a deployment
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
'200':
description: Returns the deployment for a deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once deployment is
finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch
once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will be merged
into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with this
deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy error,
if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the deploy
operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable of
dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation was
last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy operation
summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy operation
summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the deploy
operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this operation
summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by the
deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the
deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is
capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the deploy
operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment from
completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in this
deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is
currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is paused, if
known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
Get the deployment for a deploy request
### 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**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/operations:
get:
tags:
- Deploy requests
operationId: list_deploy_operations
summary: List deploy operations
parameters:
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns deploy operations for the deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy error,
if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the deploy
operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable of
dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation was
last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
List deploy operations for a deploy request
### 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**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/revert:
post:
tags:
- Deploy requests
operationId: complete_revert
summary: Complete a revert
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
'200':
description: Returns the deploy request that was reverted
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
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
closed_by:
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
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
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
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: >-
The name of the branch the deploy request will be merged
into
into_branch_sharded:
type: boolean
description: >-
Whether or not the branch the deploy request will be
merged into is sharded
into_branch_shard_count:
type: integer
description: >-
The number of shards the branch the deploy request will be
merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once
deployment is finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch
once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will be
merged into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with this
deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy
error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable
of dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: >-
The DDL statement for the deploy operation
summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy operation
summary
operation_name:
type: string
description: >-
The operation name of the deploy operation
summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy operation
summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
summary was last used
nullable: true
throttled_at:
type: string
description: >-
When the deploy operation summary was last
throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this operation
summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by
the deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the
deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is
capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the
deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for
the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment from
completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in this
deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: >-
The name of the table that is locked by the
deployment.
nullable: true
instant_ddl:
type: boolean
description: >-
Whether or not the deployment is an instant DDL
deployment
instant_ddl_eligible:
type: boolean
description: >-
Whether or not the deployment is eligible for instant
DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is
currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is paused, if
known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/reviews:
get:
tags:
- Deploy requests
operationId: list_deploy_request_reviews
summary: List deploy request reviews
parameters:
- name: organization
in: path
required: true
description: The name of the organization the deploy request belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the deploy request belongs to
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns an array of deploy request reviews
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the review
body:
type: string
description: The text body of the review
html_body:
type: string
description: The HTML body of the review
state:
type: string
enum:
- commented
- approved
description: Whether the review is a comment or approval
created_at:
type: string
description: When the review was created
updated_at:
type: string
description: When the review was last updated
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
- body
- html_body
- state
- created_at
- updated_at
- actor
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
post:
tags:
- Deploy requests
operationId: review_deploy_request
summary: Review a deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the organization the deploy request belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the deploy request belongs to
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
state:
type: string
enum:
- commented
- approved
description: >-
Whether the review is a comment or approval. Service tokens
must have corresponding access (either
`approve_deploy_request` or `review_deploy_request`)
body:
type: string
description: Deploy request review comments
responses:
'201':
description: Returns the created deploy request review
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the review
body:
type: string
description: The text body of the review
html_body:
type: string
description: The HTML body of the review
state:
type: string
enum:
- commented
- approved
description: Whether the review is a comment or approval
created_at:
type: string
description: When the review was created
updated_at:
type: string
description: When the review was last updated
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
- body
- html_body
- state
- created_at
- updated_at
- actor
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
Review a deploy request by either approving or commenting on the deploy
request
### 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**
`approve_deploy_request`, `review_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `approve_deploy_requests` |
| Database | `approve_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/skip-revert:
post:
tags:
- Deploy requests
operationId: skip_revert_period
summary: Skip revert period
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
'200':
description: Returns the deploy request whose deploy revert was skipped
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
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
closed_by:
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
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
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
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: >-
The name of the branch the deploy request will be merged
into
into_branch_sharded:
type: boolean
description: >-
Whether or not the branch the deploy request will be
merged into is sharded
into_branch_shard_count:
type: integer
description: >-
The number of shards the branch the deploy request will be
merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once
deployment is finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch
once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will be
merged into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with this
deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy
error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable
of dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: >-
The DDL statement for the deploy operation
summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy operation
summary
operation_name:
type: string
description: >-
The operation name of the deploy operation
summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy operation
summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the
deploy operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
summary was last used
nullable: true
throttled_at:
type: string
description: >-
When the deploy operation summary was last
throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this operation
summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by
the deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the
deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is
capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the
deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for
the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment from
completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in this
deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: >-
The name of the table that is locked by the
deployment.
nullable: true
instant_ddl:
type: boolean
description: >-
Whether or not the deployment is an instant DDL
deployment
instant_ddl_eligible:
type: boolean
description: >-
Whether or not the deployment is eligible for instant
DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is
currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is paused, if
known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
Skips the revert period for a deploy request
### 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**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/storage-check:
get:
tags:
- Deploy requests
operationId: check_deploy_request_storage
summary: Check deploy request storage
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
'200':
description: Returns storage check information for the deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
enough_storage:
type: boolean
description: Whether the cluster has enough storage to safely deploy
upgradeable:
type: boolean
description: >-
Whether the target branch cluster can be upgraded for more
storage
storage_bytes_needed:
type: integer
description: >-
Total estimated bytes of additional storage needed for the
deployment
storage_report:
type: object
additionalProperties:
type: object
description: Per-shard storage details. Keys are shard names.
additionalProperties:
type: object
properties:
used:
type: integer
description: Current storage used in bytes
capacity:
type: integer
description: Total storage capacity in bytes
remaining:
type: integer
description: Remaining storage available in bytes
percentage_used:
type: number
description: Percentage of storage capacity currently used
storage_needed:
type: integer
description: >-
Estimated additional storage needed for this
deployment in bytes
has_enough:
type: boolean
description: >-
Whether this shard has enough remaining storage
for the deployment
description: >-
Per-keyspace and per-shard storage report. Keys are
keyspace names.
required:
- enough_storage
- upgradeable
- storage_bytes_needed
- storage_report
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
Checks whether the deploy request's target branch cluster has enough
storage to safely deploy the schema changes.
### 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**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/throttler:
get:
tags:
- Deploy requests
operationId: get_deploy_request_throttler
summary: Get deploy request throttler configurations
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
'200':
description: Deploy request throttler configurations
headers: {}
content:
application/json:
schema:
type: object
properties:
keyspaces:
items:
type: string
type: array
description: >-
Keyspaces that are eligible for throttler configuration in
the configurable resource (database or deploy request)
configurable:
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
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: >-
A throttler ratio between 0 and 95 that applies to
migrations in this specific keyspace
required:
- keyspace_name
- ratio
required:
- keyspaces
- configurable
- configurations
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
patch:
tags:
- Deploy requests
operationId: update_deploy_request_throttler
summary: Update deploy request throttler configurations
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
ratio:
type: integer
description: >-
A throttler ratio between 0 and 95 that will apply to all
keyspaces affected by the deploy request. 0 effectively
disables throttler, while 95 drastically slows down
migrations in the deploy request
configurations:
type: array
items:
type: string
description: >-
If specifying throttler ratios per keyspace, an array of {
"keyspace_name": "mykeyspace", "ratio": 10 }, one for each
eligible keyspace
responses:
'200':
description: Deploy request throttler configurations
headers: {}
content:
application/json:
schema:
type: object
properties:
keyspaces:
items:
type: string
type: array
description: >-
Keyspaces that are eligible for throttler configuration in
the configurable resource (database or deploy request)
configurable:
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
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: >-
A throttler ratio between 0 and 95 that applies to
migrations in this specific keyspace
required:
- keyspace_name
- ratio
required:
- keyspaces
- configurable
- configurations
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/maintenance-schedules:
get:
tags:
- MaintenanceSchedules
operationId: list_maintenance_schedules
summary: List maintenance schedules
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: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns maintenance schedules for the database
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the maintenance schedule
name:
type: string
description: The display name of the maintenance schedule
created_at:
type: string
description: When the maintenance schedule was created
updated_at:
type: string
description: When the maintenance schedule was last updated
last_window_datetime:
type: string
description: When the last maintenance window started
next_window_datetime:
type: string
description: When the next maintenance window is scheduled
duration:
type: integer
description: The duration of the maintenance window in hours
day:
type: integer
description: >-
Day of the week (0 = Sunday, 6 = Saturday, 7 = every
day)
hour:
type: integer
description: Hour of the day in UTC (0-23)
week:
type: integer
description: Week of the month for monthly schedules (0-3)
frequency_value:
type: integer
description: The frequency value of the maintenance schedule
frequency_unit:
type: string
enum:
- day
- week
- month
- once
description: The frequency unit of the maintenance schedule
enabled:
type: boolean
description: Whether the maintenance schedule is enabled
expires_at:
type: string
description: When a one-time maintenance schedule expires
nullable: true
deadline_at:
type: string
description: The deadline for a required maintenance schedule
nullable: true
required:
type: boolean
description: Whether the maintenance schedule is required
pending_vitess_version_update:
type: boolean
description: Whether there is a pending Vitess version update
pending_vitess_version:
type: string
description: The pending Vitess version, if any
nullable: true
pending_mysql_version_update:
type: boolean
description: Whether there is a pending MySQL version update
pending_mysql_version:
type: string
description: The pending MySQL version, if any
nullable: true
required:
- id
- name
- created_at
- updated_at
- last_window_datetime
- next_window_datetime
- duration
- day
- hour
- week
- frequency_value
- frequency_unit
- enabled
- expires_at
- deadline_at
- required
- pending_vitess_version_update
- pending_vitess_version
- pending_mysql_version_update
- pending_mysql_version
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/maintenance-schedules/{id}:
get:
tags:
- MaintenanceSchedules
operationId: get_maintenance_schedule
summary: Get a maintenance schedule
parameters:
- name: id
in: path
required: true
description: The ID of the maintenance schedule
schema:
type: string
- 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
responses:
'200':
description: Returns a maintenance schedule
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the maintenance schedule
name:
type: string
description: The display name of the maintenance schedule
created_at:
type: string
description: When the maintenance schedule was created
updated_at:
type: string
description: When the maintenance schedule was last updated
last_window_datetime:
type: string
description: When the last maintenance window started
next_window_datetime:
type: string
description: When the next maintenance window is scheduled
duration:
type: integer
description: The duration of the maintenance window in hours
day:
type: integer
description: Day of the week (0 = Sunday, 6 = Saturday, 7 = every day)
hour:
type: integer
description: Hour of the day in UTC (0-23)
week:
type: integer
description: Week of the month for monthly schedules (0-3)
frequency_value:
type: integer
description: The frequency value of the maintenance schedule
frequency_unit:
type: string
enum:
- day
- week
- month
- once
description: The frequency unit of the maintenance schedule
enabled:
type: boolean
description: Whether the maintenance schedule is enabled
expires_at:
type: string
description: When a one-time maintenance schedule expires
nullable: true
deadline_at:
type: string
description: The deadline for a required maintenance schedule
nullable: true
required:
type: boolean
description: Whether the maintenance schedule is required
pending_vitess_version_update:
type: boolean
description: Whether there is a pending Vitess version update
pending_vitess_version:
type: string
description: The pending Vitess version, if any
nullable: true
pending_mysql_version_update:
type: boolean
description: Whether there is a pending MySQL version update
pending_mysql_version:
type: string
description: The pending MySQL version, if any
nullable: true
required:
- id
- name
- created_at
- updated_at
- last_window_datetime
- next_window_datetime
- duration
- day
- hour
- week
- frequency_value
- frequency_unit
- enabled
- expires_at
- deadline_at
- required
- pending_vitess_version_update
- pending_vitess_version
- pending_mysql_version_update
- pending_mysql_version
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/maintenance-schedules/{id}/windows:
get:
tags:
- MaintenanceWindows
operationId: list_maintenance_windows
summary: List maintenance windows
parameters:
- name: id
in: path
required: true
description: The ID of the maintenance schedule
schema:
type: string
- 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: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns maintenance windows for the schedule
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the maintenance window
created_at:
type: string
description: When the maintenance window was created
updated_at:
type: string
description: When the maintenance window was last updated
started_at:
type: string
description: When the maintenance window started
nullable: true
finished_at:
type: string
description: When the maintenance window finished
nullable: true
required:
- id
- created_at
- updated_at
- started_at
- finished_at
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/read-only-regions:
get:
tags:
- Databases
operationId: list_read_only_regions
summary: List read-only regions
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: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: List of the database's read-only regions
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the read-only region
display_name:
type: string
description: The name of the read-only region
created_at:
type: string
description: When the read-only region was created
updated_at:
type: string
description: When the read-only region was last updated
ready_at:
type: string
description: When the read-only region was ready to serve queries
nullable: true
ready:
type: boolean
description: >-
Whether or not the read-only region 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
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
required:
- id
- display_name
- created_at
- updated_at
- ready_at
- ready
- actor
- region
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
List read-only regions for the database's default 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**
`read_database`, `delete_database`, `write_database`, `read_branch`, `delete_branch`, `create_branch`, `delete_production_branch`, `connect_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `delete_branch_password`, `delete_production_branch_password`, `delete_production_read_only_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_comment`, `create_comment`, `restore_backup`, `restore_production_branch_backup`, `read_backups`, `write_backups`, `delete_backups`, `delete_production_branch_backups`, `write_branch_vschema`, `write_production_branch_vschema`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
/organizations/{organization}/databases/{database}/regions:
get:
tags:
- Databases
operationId: list_database_regions
summary: List database regions
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: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns the available regions for a database
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
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
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_database`, `delete_database`, `write_database`, `read_branch`, `delete_branch`, `create_branch`, `delete_production_branch`, `connect_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `delete_branch_password`, `delete_production_branch_password`, `delete_production_read_only_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_comment`, `create_comment`, `restore_backup`, `restore_production_branch_backup`, `read_backups`, `write_backups`, `delete_backups`, `delete_production_branch_backups`, `write_branch_vschema`, `write_production_branch_vschema`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/schema-recommendations:
get:
tags:
- Schema recommendations
operationId: list_schema_recommendations
summary: List schema recommendations
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: state
in: query
description: Filter by recommendation state
schema:
type: string
enum:
- open
- closed
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns schema recommendations
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the schema recommendation
html_url:
type: string
description: The URL to the schema recommendation in the app
title:
type: string
description: The title of the schema recommendation
table_name:
type: string
description: The name of the table the recommendation applies to
keyspace:
type: string
description: The keyspace the recommendation applies to
ddl_statement:
type: string
description: The DDL statement to apply the recommendation
number:
type: integer
description: The number of the schema recommendation
state:
type: string
enum:
- open
- applied
- dismissed
- stale
description: The state of the recommendation
recommendation_type:
type: string
enum:
- unused_table
- unused_index
- duplicate_index
- sequence_overflow
- sequence_overflow_foreign_key
- new_index
- encoding_upgrade
- bloated_table
- bloated_index
description: The type of recommendation
created_at:
type: string
description: When the recommendation was created
updated_at:
type: string
description: When the recommendation was last updated
applied_at:
type: string
description: When the recommendation was applied
nullable: true
dismissed_at:
type: string
description: When the recommendation was dismissed
nullable: true
closed_by_deploy_request:
type: object
properties:
id:
type: string
description: The ID of the deploy request
branch_id:
type: string
description: The ID of the branch
number:
type: integer
description: The number of the deploy request
required:
- id
- branch_id
- number
nullable: true
dismissed_by:
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
required:
- id
- html_url
- title
- table_name
- keyspace
- ddl_statement
- number
- state
- recommendation_type
- created_at
- updated_at
- applied_at
- dismissed_at
- closed_by_deploy_request
- dismissed_by
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/schema-recommendations/{number}:
get:
tags:
- Schema recommendations
operationId: get_schema_recommendation
summary: Get a schema recommendation
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: number
in: path
required: true
description: 'Schema recommendation sequence number. Example: `42`.'
schema:
type: integer
responses:
'200':
description: Returns a schema recommendation
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the schema recommendation
html_url:
type: string
description: The URL to the schema recommendation in the app
title:
type: string
description: The title of the schema recommendation
table_name:
type: string
description: The name of the table the recommendation applies to
keyspace:
type: string
description: The keyspace the recommendation applies to
ddl_statement:
type: string
description: The DDL statement to apply the recommendation
number:
type: integer
description: The number of the schema recommendation
state:
type: string
enum:
- open
- applied
- dismissed
- stale
description: The state of the recommendation
recommendation_type:
type: string
enum:
- unused_table
- unused_index
- duplicate_index
- sequence_overflow
- sequence_overflow_foreign_key
- new_index
- encoding_upgrade
- bloated_table
- bloated_index
description: The type of recommendation
created_at:
type: string
description: When the recommendation was created
updated_at:
type: string
description: When the recommendation was last updated
applied_at:
type: string
description: When the recommendation was applied
nullable: true
dismissed_at:
type: string
description: When the recommendation was dismissed
nullable: true
closed_by_deploy_request:
type: object
properties:
id:
type: string
description: The ID of the deploy request
branch_id:
type: string
description: The ID of the branch
number:
type: integer
description: The number of the deploy request
required:
- id
- branch_id
- number
nullable: true
dismissed_by:
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
required:
- id
- html_url
- title
- table_name
- keyspace
- ddl_statement
- number
- state
- recommendation_type
- created_at
- updated_at
- applied_at
- dismissed_at
- closed_by_deploy_request
- dismissed_by
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/schema-recommendations/{number}/dismiss:
post:
tags:
- Schema recommendations
operationId: dismiss_schema_recommendation
summary: Dismiss a schema recommendation
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: number
in: path
required: true
description: 'Schema recommendation sequence number. Example: `42`.'
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: >-
The reason for dismissing the recommendation (max 500
characters)
responses:
'200':
description: Returns the dismissed schema recommendation
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the schema recommendation
html_url:
type: string
description: The URL to the schema recommendation in the app
title:
type: string
description: The title of the schema recommendation
table_name:
type: string
description: The name of the table the recommendation applies to
keyspace:
type: string
description: The keyspace the recommendation applies to
ddl_statement:
type: string
description: The DDL statement to apply the recommendation
number:
type: integer
description: The number of the schema recommendation
state:
type: string
enum:
- open
- applied
- dismissed
- stale
description: The state of the recommendation
recommendation_type:
type: string
enum:
- unused_table
- unused_index
- duplicate_index
- sequence_overflow
- sequence_overflow_foreign_key
- new_index
- encoding_upgrade
- bloated_table
- bloated_index
description: The type of recommendation
created_at:
type: string
description: When the recommendation was created
updated_at:
type: string
description: When the recommendation was last updated
applied_at:
type: string
description: When the recommendation was applied
nullable: true
dismissed_at:
type: string
description: When the recommendation was dismissed
nullable: true
closed_by_deploy_request:
type: object
properties:
id:
type: string
description: The ID of the deploy request
branch_id:
type: string
description: The ID of the branch
number:
type: integer
description: The number of the deploy request
required:
- id
- branch_id
- number
nullable: true
dismissed_by:
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
required:
- id
- html_url
- title
- table_name
- keyspace
- ddl_statement
- number
- state
- recommendation_type
- created_at
- updated_at
- applied_at
- dismissed_at
- closed_by_deploy_request
- dismissed_by
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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` |
/organizations/{organization}/databases/{database}/throttler:
get:
tags:
- Databases
operationId: get_database_throttler
summary: Get database throttler configurations
parameters:
- name: organization
in: path
required: true
description: >-
The name of the organization that the throttled deploy requests
belong to
schema:
type: string
- name: database
in: path
required: true
description: >-
The name of the database that the throttled deploy requests belong
to
schema:
type: string
responses:
'200':
description: Database throttler configurations
headers: {}
content:
application/json:
schema:
type: object
properties:
keyspaces:
items:
type: string
type: array
description: >-
Keyspaces that are eligible for throttler configuration in
the configurable resource (database or deploy request)
configurable:
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
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: >-
A throttler ratio between 0 and 95 that applies to
migrations in this specific keyspace
required:
- keyspace_name
- ratio
required:
- keyspaces
- configurable
- configurations
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
patch:
tags:
- Databases
operationId: update_database_throttler
summary: Update database throttler configurations
parameters:
- name: organization
in: path
required: true
description: >-
The name of the organization that the throttled deploy requests
belong to
schema:
type: string
- name: database
in: path
required: true
description: >-
The name of the database that the throttled deploy requests belong
to
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
ratio:
type: integer
description: >-
A throttler ratio between 0 and 95 that will apply to all
keyspaces in the database. 0 effectively disables throttler,
while 95 drastically slows down deploy request migrations
configurations:
type: array
items:
type: string
description: >-
If specifying throttler ratios per keyspace, an array of {
"keyspace_name": "mykeyspace", "ratio": 10 }, one for each
eligible keyspace
responses:
'200':
description: Database throttler configurations
headers: {}
content:
application/json:
schema:
type: object
properties:
keyspaces:
items:
type: string
type: array
description: >-
Keyspaces that are eligible for throttler configuration in
the configurable resource (database or deploy request)
configurable:
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
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: >-
A throttler ratio between 0 and 95 that applies to
migrations in this specific keyspace
required:
- keyspace_name
- ratio
required:
- keyspaces
- configurable
- configurations
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/webhooks:
get:
tags:
- Webhooks
operationId: list_webhooks
summary: List webhooks
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns a list of webhooks for a database
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
nullable: true
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
List webhooks for a database
### 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**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
post:
tags:
- Webhooks
operationId: create_webhook
summary: Create a webhook
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
url:
type: string
description: The URL the webhook will send events to
enabled:
type: boolean
description: Whether the webhook should be enabled
events:
type: array
items:
type: string
description: The events this webhook should subscribe to
required:
- url
responses:
'201':
description: Returns the created webhook
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
nullable: true
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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` |
/organizations/{organization}/databases/{database}/webhooks/{id}:
get:
tags:
- Webhooks
operationId: get_webhook
summary: Get a webhook
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the webhook
schema:
type: string
responses:
'200':
description: Returns the webhook
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
nullable: true
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
patch:
tags:
- Webhooks
operationId: update_webhook
summary: Update a webhook
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the webhook
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
url:
type: string
description: The URL the webhook will send events to
enabled:
type: boolean
description: Whether the webhook should be enabled
events:
type: array
items:
type: string
description: The events this webhook should subscribe to
responses:
'200':
description: Returns the updated webhook
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
nullable: true
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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` |
delete:
tags:
- Webhooks
operationId: delete_webhook
summary: Delete a webhook
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the webhook
schema:
type: string
responses:
'204':
description: Webhook successfully deleted
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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` |
/organizations/{organization}/databases/{database}/webhooks/{id}/test:
post:
tags:
- Webhooks
operationId: test_webhook
summary: Test a webhook
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the webhook
schema:
type: string
responses:
'204':
description: Webhook test event successfully triggered
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
Sends a test event to the webhook
### 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` |
/organizations/{organization}/databases/{database}/workflows:
get:
tags:
- Workflows
operationId: list_workflows
summary: List workflows
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: between
in: query
description: >-
Filter workflows to those active during a time range (e.g.
2025-01-01T00:00:00Z..2025-01-01T23:59:59)
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns workflows
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
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
verify_data_by:
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
reversed_by:
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
switch_replicas_by:
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
switch_primaries_by:
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
cancelled_by:
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
completed_by:
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
retried_by:
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
cutover_by:
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
reversed_cutover_by:
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
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
source_keyspace:
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
target_keyspace:
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
global_keyspace:
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
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: |+
post:
tags:
- Workflows
operationId: create_workflow
summary: Create a workflow
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name the workflow
source_keyspace:
type: string
description: Name of the source keyspace
target_keyspace:
type: string
description: Name of the target keyspace
global_keyspace:
type: string
description: Name of the global sequence keyspace
defer_secondary_keys:
type: boolean
description: Defer secondary keys
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
tables:
type: array
items:
type: string
description: List of tables to move
required:
- name
- source_keyspace
- target_keyspace
- tables
responses:
'201':
description: Returns the workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
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
verify_data_by:
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
reversed_by:
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
switch_replicas_by:
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
switch_primaries_by:
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
cancelled_by:
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
completed_by:
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
retried_by:
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
cutover_by:
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
reversed_cutover_by:
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
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
source_keyspace:
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
target_keyspace:
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
global_keyspace:
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
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}:
get:
tags:
- Workflows
operationId: get_workflow
summary: Get a workflow
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
'200':
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
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
verify_data_by:
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
reversed_by:
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
switch_replicas_by:
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
switch_primaries_by:
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
cancelled_by:
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
completed_by:
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
retried_by:
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
cutover_by:
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
reversed_cutover_by:
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
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
source_keyspace:
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
target_keyspace:
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
global_keyspace:
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
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: |+
delete:
tags:
- Workflows
operationId: workflow_cancel
summary: Cancel a workflow
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
'200':
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
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
verify_data_by:
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
reversed_by:
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
switch_replicas_by:
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
switch_primaries_by:
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
cancelled_by:
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
completed_by:
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
retried_by:
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
cutover_by:
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
reversed_cutover_by:
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
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
source_keyspace:
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
target_keyspace:
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
global_keyspace:
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
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/complete:
patch:
tags:
- Workflows
operationId: workflow_complete
summary: Complete a workflow
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
'200':
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
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
verify_data_by:
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
reversed_by:
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
switch_replicas_by:
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
switch_primaries_by:
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
cancelled_by:
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
completed_by:
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
retried_by:
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
cutover_by:
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
reversed_cutover_by:
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
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
source_keyspace:
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
target_keyspace:
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
global_keyspace:
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
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/cutover:
patch:
tags:
- Workflows
operationId: workflow_cutover
summary: Cutover traffic
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
'200':
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
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
verify_data_by:
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
reversed_by:
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
switch_replicas_by:
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
switch_primaries_by:
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
cancelled_by:
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
completed_by:
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
retried_by:
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
cutover_by:
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
reversed_cutover_by:
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
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
source_keyspace:
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
target_keyspace:
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
global_keyspace:
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
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/retry:
patch:
tags:
- Workflows
operationId: workflow_retry
summary: Retry a failed workflow
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
'200':
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
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
verify_data_by:
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
reversed_by:
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
switch_replicas_by:
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
switch_primaries_by:
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
cancelled_by:
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
completed_by:
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
retried_by:
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
cutover_by:
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
reversed_cutover_by:
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
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
source_keyspace:
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
target_keyspace:
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
global_keyspace:
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
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/reverse-cutover:
patch:
tags:
- Workflows
operationId: workflow_reverse_cutover
summary: Reverse traffic cutover
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
'200':
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
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
verify_data_by:
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
reversed_by:
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
switch_replicas_by:
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
switch_primaries_by:
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
cancelled_by:
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
completed_by:
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
retried_by:
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
cutover_by:
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
reversed_cutover_by:
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
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
source_keyspace:
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
target_keyspace:
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
global_keyspace:
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
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/reverse-traffic:
patch:
tags:
- Workflows
operationId: workflow_reverse_traffic
summary: Reverse traffic
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
'200':
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
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
verify_data_by:
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
reversed_by:
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
switch_replicas_by:
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
switch_primaries_by:
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
cancelled_by:
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
completed_by:
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
retried_by:
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
cutover_by:
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
reversed_cutover_by:
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
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
source_keyspace:
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
target_keyspace:
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
global_keyspace:
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
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/switch-primaries:
patch:
tags:
- Workflows
operationId: workflow_switch_primaries
summary: Switch primary traffic
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
'200':
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
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
verify_data_by:
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
reversed_by:
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
switch_replicas_by:
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
switch_primaries_by:
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
cancelled_by:
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
completed_by:
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
retried_by:
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
cutover_by:
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
reversed_cutover_by:
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
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
source_keyspace:
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
target_keyspace:
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
global_keyspace:
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
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/switch-replicas:
patch:
tags:
- Workflows
operationId: workflow_switch_replicas
summary: Switch replica traffic
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
'200':
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
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
verify_data_by:
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
reversed_by:
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
switch_replicas_by:
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
switch_primaries_by:
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
cancelled_by:
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
completed_by:
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
retried_by:
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
cutover_by:
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
reversed_cutover_by:
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
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
source_keyspace:
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
target_keyspace:
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
global_keyspace:
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
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/verify-data:
patch:
tags:
- Workflows
operationId: verify_workflow
summary: Verify workflow data
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
'200':
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
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
verify_data_by:
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
reversed_by:
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
switch_replicas_by:
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
switch_primaries_by:
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
cancelled_by:
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
completed_by:
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
retried_by:
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
cutover_by:
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
reversed_cutover_by:
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
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
source_keyspace:
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
target_keyspace:
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
global_keyspace:
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
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: |+
/organizations/{organization}/invoices:
get:
tags:
- Invoices
operationId: list_invoices
summary: Get invoices
parameters:
- name: organization
in: path
required: true
description: 'Organization name slug from `list_organizations`. Example: `acme`.'
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Gets the invoices for an organization
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the invoice
total:
type: string
description: >-
The total amount of the invoice, as a stringified
decimal to preserve precision
billing_period_start:
type: string
description: Start of the billing period
billing_period_end:
type: string
description: End of the billing period
paid:
type: boolean
description: Whether the invoice has been paid
overdue:
type: boolean
description: Whether the invoice is past due and unpaid
required:
- id
- total
- billing_period_start
- billing_period_end
- paid
- overdue
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
Get the invoices for an organization
### 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**
`read_invoices`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_invoices` |
/organizations/{organization}/invoices/{id}:
get:
tags:
- Invoices
operationId: get_invoice
summary: Get an invoice
parameters:
- name: organization
in: path
required: true
description: 'Organization name slug from `list_organizations`. Example: `acme`.'
schema:
type: string
- name: id
in: path
required: true
description: 'Invoice public ID from `list_invoices`. Example: `aabb12123434`.'
schema:
type: string
responses:
'200':
description: Returns an invoice
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the invoice
total:
type: string
description: >-
The total amount of the invoice, as a stringified decimal
to preserve precision
billing_period_start:
type: string
description: Start of the billing period
billing_period_end:
type: string
description: End of the billing period
paid:
type: boolean
description: Whether the invoice has been paid
overdue:
type: boolean
description: Whether the invoice is past due and unpaid
required:
- id
- total
- billing_period_start
- billing_period_end
- paid
- overdue
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_invoices`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_invoices` |
/organizations/{organization}/invoices/{id}/line-items:
get:
tags:
- Invoices
operationId: get_invoice_line_items
summary: Get invoice line items
parameters:
- name: organization
in: path
required: true
description: 'Organization name slug from `list_organizations`. Example: `acme`.'
schema:
type: string
- name: id
in: path
required: true
description: 'Invoice public ID from `list_invoices`. Example: `aabb12123434`.'
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Gets the line items for an invoice
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the line item
subtotal:
type: number
description: The total for the line item
description:
type: string
description: The description for the line item
metric_name:
type: string
description: The name of the billable item
database_id:
type: string
description: The ID for the billed database
database_name:
type: string
description: The name for the billed database
resource:
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
required:
- id
- subtotal
- description
- metric_name
- database_id
- database_name
- resource
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
Get the line items for an invoice
### 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**
`read_invoices`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_invoices` |
/organizations/{organization}/members:
get:
tags:
- Organization members
operationId: list_organization_members
summary: List organization members
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: q
in: query
description: Search term to filter members by name or email
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns members of the organization
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two
factor authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an
authentication provider.
nullable: true
directory_managed:
type: boolean
description: >-
Whether or not the user is managed by a SSO
directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
required:
- id
- user
- role
- created_at
- updated_at
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_organization` |
/organizations/{organization}/members/{id}:
get:
tags:
- Organization members
operationId: get_organization_membership
summary: Get an organization member
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: id
in: path
required: true
description: The ID of the user
schema:
type: string
responses:
'200':
description: Returns the membership of the user in the organization
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two factor
authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an
authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
required:
- id
- user
- role
- created_at
- updated_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_organization` |
patch:
tags:
- Organization members
operationId: update_organization_membership
summary: Update organization member role
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: id
in: path
required: true
description: The ID of the user
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
role:
type: string
description: >-
The role to assign to the member (e.g., 'admin', 'member').
Note: Cannot update your own role. Roles managed by IdP
cannot be updated via API.
required:
- role
responses:
'200':
description: Returns the updated membership
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two factor
authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an
authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
required:
- id
- user
- role
- created_at
- updated_at
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
delete:
tags:
- Organization members
operationId: remove_organization_member
summary: Remove a member from an organization
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: id
in: path
required: true
description: The ID of the user
schema:
type: string
- name: delete_passwords
in: query
description: >-
Whether to delete all passwords associated with the member. Only
available when removing other members (not yourself).
schema:
type: boolean
- name: delete_service_tokens
in: query
description: >-
Whether to delete all service tokens associated with the member.
Only available when removing other members (not yourself).
schema:
type: boolean
responses:
'204':
description: >-
Member removed successfully. Note: Cannot remove the last admin or
leave your only organization.
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
/organizations/{organization}/oauth-applications:
get:
tags:
- OAuth applications
operationId: list_oauth_applications
summary: List OAuth applications
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth applications belong to
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns a list of the organization's oauth applications
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the app
name:
type: string
description: The name of the app
redirect_uri:
type: string
description: The redirect URI of the OAuth application
domain:
type: string
description: >-
The domain of the OAuth application. Used for
verification of a valid redirect uri
created_at:
type: string
description: When the OAuth application was created
updated_at:
type: string
description: When the OAuth application was last updated
scopes:
type: string
description: >-
The scopes that the OAuth application requires on a
user account, as a space-separated string
avatar:
type: string
description: The image source for the OAuth application's avatar
client_id:
type: string
description: The OAuth application's unique client id
tokens:
type: integer
description: The number of tokens issued by the OAuth application
dcr:
type: boolean
description: >-
Whether the OAuth application was created via
Dynamic Client Registration
single_org_authorization:
type: boolean
description: >-
Whether the OAuth application is limited to
authorizing a single organization
scopes_by_resource:
type: object
additionalProperties: true
description: >-
Scopes grouped by resource type (database,
organization, branch, user) with scope, description,
and admin flag
all_scopes_by_resource:
type: object
additionalProperties: true
description: >-
All available scopes grouped by resource type with
scope, description, selected, and admin flags
required:
- id
- name
- redirect_uri
- domain
- created_at
- updated_at
- scopes
- avatar
- client_id
- tokens
- dcr
- single_org_authorization
- scopes_by_resource
- all_scopes_by_resource
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`read_oauth_applications`
/organizations/{organization}/oauth-applications/{application_id}:
get:
tags:
- OAuth applications
operationId: get_oauth_application
summary: Get an OAuth application
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth application belongs to
schema:
type: string
- name: application_id
in: path
required: true
description: The ID of the OAuth application
schema:
type: string
responses:
'200':
description: Returns information abuot an OAuth application
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the app
name:
type: string
description: The name of the app
redirect_uri:
type: string
description: The redirect URI of the OAuth application
domain:
type: string
description: >-
The domain of the OAuth application. Used for verification
of a valid redirect uri
created_at:
type: string
description: When the OAuth application was created
updated_at:
type: string
description: When the OAuth application was last updated
scopes:
type: string
description: >-
The scopes that the OAuth application requires on a user
account, as a space-separated string
avatar:
type: string
description: The image source for the OAuth application's avatar
client_id:
type: string
description: The OAuth application's unique client id
tokens:
type: integer
description: The number of tokens issued by the OAuth application
dcr:
type: boolean
description: >-
Whether the OAuth application was created via Dynamic
Client Registration
single_org_authorization:
type: boolean
description: >-
Whether the OAuth application is limited to authorizing a
single organization
scopes_by_resource:
type: object
additionalProperties: true
description: >-
Scopes grouped by resource type (database, organization,
branch, user) with scope, description, and admin flag
all_scopes_by_resource:
type: object
additionalProperties: true
description: >-
All available scopes grouped by resource type with scope,
description, selected, and admin flags
required:
- id
- name
- redirect_uri
- domain
- created_at
- updated_at
- scopes
- avatar
- client_id
- tokens
- dcr
- single_org_authorization
- scopes_by_resource
- all_scopes_by_resource
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`read_oauth_applications`
/organizations/{organization}/oauth-applications/{application_id}/tokens:
get:
tags:
- OAuth applications
operationId: list_oauth_tokens
summary: List OAuth tokens
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth application belongs to
schema:
type: string
- name: application_id
in: path
required: true
description: The ID of the OAuth application
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns the OAuth tokens issued on behalf of the OAuth application
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: >-
The plaintext refresh token. Available only after
create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: >-
The ID of the actor on whose behalf the service
token was created
nullable: true
actor_display_name:
type: string
description: >-
The name of the actor on whose behalf the service
token was created
nullable: true
actor_type:
type: string
description: >-
The type of the actor on whose behalf the service
token was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: >-
The name of the resource the service token
access gives access to
resource_id:
type: string
description: >-
The ID of the resource the service token
access gives access to
resource_type:
type: string
description: >-
The type of the resource the service token
access gives access to
resource:
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
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: >-
the name of the database the token has
access to
id:
type: string
description: >-
the id of the database the token has
access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: >-
the planetscale app url for the
organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: >-
the name of the database the branch
belongs to
organization:
type: string
description: >-
the name of the organization the branch
belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
List OAuth tokens created by an OAuth application
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`read_oauth_tokens`
/organizations/{organization}/oauth-applications/{application_id}/tokens/{token_id}:
get:
tags:
- OAuth applications
operationId: get_oauth_token
summary: Get an OAuth token
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth application belongs to
schema:
type: string
- name: application_id
in: path
required: true
description: The ID of the OAuth application
schema:
type: string
- name: token_id
in: path
required: true
description: The ID of the OAuth application token
schema:
type: string
responses:
'200':
description: >-
Returns an OAuth token that was issued on behalf of the OAuth
application
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: >-
The ID of the actor on whose behalf the service token was
created
nullable: true
actor_display_name:
type: string
description: >-
The name of the actor on whose behalf the service token
was created
nullable: true
actor_type:
type: string
description: >-
The type of the actor on whose behalf the service token
was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: >-
The name of the resource the service token access
gives access to
resource_id:
type: string
description: >-
The ID of the resource the service token access
gives access to
resource_type:
type: string
description: >-
The type of the resource the service token access
gives access to
resource:
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
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: >-
the name of the database the token has
access to
id:
type: string
description: >-
the id of the database the token has access
to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: >-
the name of the database the branch belongs
to
organization:
type: string
description: >-
the name of the organization the branch
belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`read_oauth_tokens`
delete:
tags:
- OAuth applications
operationId: delete_oauth_token
summary: Delete an OAuth token
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth application belongs to
schema:
type: string
- name: application_id
in: path
required: true
description: The ID of the OAuth application
schema:
type: string
- name: token_id
in: path
required: true
description: The ID of the OAuth application token
schema:
type: string
responses:
'204':
description: Deletes an OAuth application's OAuth token
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`delete_oauth_tokens`
/organizations/{organization}/oauth-applications/{id}/token:
post:
tags:
- OAuth tokens
operationId: create_oauth_token
summary: Create or renew an OAuth token
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth application belongs to
schema:
type: string
- name: id
in: path
required: true
description: The ID of the OAuth application
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
client_id:
type: string
description: The OAuth application's client ID
client_secret:
type: string
description: The OAuth application's client secret
grant_type:
type: string
enum:
- authorization_code
- refresh_token
description: >-
Whether an OAuth grant code or a refresh token is being
exchanged for an OAuth token
code:
type: string
description: >-
The OAuth grant code provided to your OAuth application's
redirect URI. Required when grant_type is authorization_code
redirect_uri:
type: string
description: >-
The OAuth application's redirect URI. Required when
grant_type is authorization_code
refresh_token:
type: string
description: >-
The refresh token from the original OAuth token grant.
Required when grant_type is refresh_token
required:
- client_id
- client_secret
- grant_type
responses:
'200':
description: Returns the created OAuth token
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: >-
The ID of the actor on whose behalf the service token was
created
nullable: true
actor_display_name:
type: string
description: >-
The name of the actor on whose behalf the service token
was created
nullable: true
actor_type:
type: string
description: >-
The type of the actor on whose behalf the service token
was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: >-
The name of the resource the service token access
gives access to
resource_id:
type: string
description: >-
The ID of the resource the service token access
gives access to
resource_type:
type: string
description: >-
The type of the resource the service token access
gives access to
resource:
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
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: >-
the name of the database the token has
access to
id:
type: string
description: >-
the id of the database the token has access
to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: >-
the name of the database the branch belongs
to
organization:
type: string
description: >-
the name of the organization the branch
belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity
'500':
description: Internal Server Error
description: >+
Create an OAuth token from an authorization grant code, or refresh an
OAuth token from a refresh token
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`write_oauth_tokens`
/organizations/{organization}/regions:
get:
tags:
- Organizations
operationId: list_regions_for_organization
summary: List regions for an organization
parameters:
- name: organization
in: path
required: true
description: 'Organization name slug from `list_organizations`. Example: `acme`.'
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns the organization's regions
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
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
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
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**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| User | `read_organizations` |
| Organization | `read_organization` |
/organizations/{organization}/service-tokens:
get:
tags:
- Service tokens
operationId: list_service_tokens
summary: List service tokens
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns the organization's service tokens
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: >-
The plaintext refresh token. Available only after
create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: >-
The ID of the actor on whose behalf the service
token was created
nullable: true
actor_display_name:
type: string
description: >-
The name of the actor on whose behalf the service
token was created
nullable: true
actor_type:
type: string
description: >-
The type of the actor on whose behalf the service
token was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: >-
The name of the resource the service token
access gives access to
resource_id:
type: string
description: >-
The ID of the resource the service token
access gives access to
resource_type:
type: string
description: >-
The type of the resource the service token
access gives access to
resource:
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
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: >-
the name of the database the token has
access to
id:
type: string
description: >-
the id of the database the token has
access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: >-
the planetscale app url for the
organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: >-
the name of the database the branch
belongs to
organization:
type: string
description: >-
the name of the organization the branch
belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
List service tokens for an organization.
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`read_service_tokens`
post:
tags:
- Service tokens
operationId: create_service_token
summary: Create a service token
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the service token
ttl:
type: integer
description: >-
Time to live (in seconds) for the service token. The token
will be invalid when TTL has passed
responses:
'200':
description: Returns the created service token with the plaintext token
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: >-
The ID of the actor on whose behalf the service token was
created
nullable: true
actor_display_name:
type: string
description: >-
The name of the actor on whose behalf the service token
was created
nullable: true
actor_type:
type: string
description: >-
The type of the actor on whose behalf the service token
was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: >-
The name of the resource the service token access
gives access to
resource_id:
type: string
description: >-
The ID of the resource the service token access
gives access to
resource_type:
type: string
description: >-
The type of the resource the service token access
gives access to
resource:
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
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: >-
the name of the database the token has
access to
id:
type: string
description: >-
the id of the database the token has access
to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: >-
the name of the database the branch belongs
to
organization:
type: string
description: >-
the name of the organization the branch
belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
Create a new service token for the organization.
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`write_service_tokens`
/organizations/{organization}/service-tokens/{id}:
get:
tags:
- Service tokens
operationId: get_service_token
summary: Get a service token
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: id
in: path
required: true
description: The ID of the service token
schema:
type: string
responses:
'200':
description: Returns the service token
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: >-
The ID of the actor on whose behalf the service token was
created
nullable: true
actor_display_name:
type: string
description: >-
The name of the actor on whose behalf the service token
was created
nullable: true
actor_type:
type: string
description: >-
The type of the actor on whose behalf the service token
was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: >-
The name of the resource the service token access
gives access to
resource_id:
type: string
description: >-
The ID of the resource the service token access
gives access to
resource_type:
type: string
description: >-
The type of the resource the service token access
gives access to
resource:
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
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: >-
the name of the database the token has
access to
id:
type: string
description: >-
the id of the database the token has access
to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: >-
the name of the database the branch belongs
to
organization:
type: string
description: >-
the name of the organization the branch
belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
Get information about a service token.
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`read_service_tokens`
delete:
tags:
- Service tokens
operationId: delete_service_token
summary: Delete a service token
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: id
in: path
required: true
description: The ID of the service token
schema:
type: string
responses:
'204':
description: Service token deleted successfully
headers: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >+
Delete a service token from the organization.
### Authorization
A service token must have at least one of the following access in
order to use this API endpoint:
**Service Token Accesses**
`delete_service_tokens`
/organizations/{organization}/teams:
get:
tags:
- Organization teams
operationId: list_organization_teams
summary: List teams in an organization
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: q
in: query
description: Search term to filter teams by name
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns teams in the organization
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the team
display_name:
type: string
description: The display name of the team
creator:
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
members:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two
factor authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an
authentication provider.
nullable: true
directory_managed:
type: boolean
description: >-
Whether or not the user is managed by a SSO
directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: >-
The URL to retrieve this database's branches
via the API
required:
- id
- name
- url
- branches_url
analyst_databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: >-
The URL to retrieve this database's branches
via the API
required:
- id
- name
- url
- branches_url
name:
type: string
description: The name of the team
slug:
type: string
description: The slug of the team
created_at:
type: string
description: When the team was created
updated_at:
type: string
description: When the team was last updated
description:
type: string
description: The description of the team
nullable: true
managed:
type: boolean
description: >-
Whether the team is managed through SSO/directory
services
required:
- id
- display_name
- creator
- members
- databases
- analyst_databases
- name
- slug
- created_at
- updated_at
- description
- managed
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'400':
description: Bad Request - Invalid operation or parameters
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity - Validation errors or SSO-managed teams
'500':
description: Internal Server Error
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**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_organization` |
post:
tags:
- Organization teams
operationId: create_organization_team
summary: Create an organization team
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the team
description:
type: string
description: A description of the team's purpose
required:
- name
responses:
'200':
description: Returns the created team
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the team
display_name:
type: string
description: The display name of the team
creator:
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
members:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two factor
authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an
authentication provider.
nullable: true
directory_managed:
type: boolean
description: >-
Whether or not the user is managed by a SSO
directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: >-
The URL to retrieve this database's branches via the
API
required:
- id
- name
- url
- branches_url
analyst_databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: >-
The URL to retrieve this database's branches via the
API
required:
- id
- name
- url
- branches_url
name:
type: string
description: The name of the team
slug:
type: string
description: The slug of the team
created_at:
type: string
description: When the team was created
updated_at:
type: string
description: When the team was last updated
description:
type: string
description: The description of the team
nullable: true
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
required:
- id
- display_name
- creator
- members
- databases
- analyst_databases
- name
- slug
- created_at
- updated_at
- description
- managed
'400':
description: Bad Request - Invalid operation or parameters
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity - Validation errors or SSO-managed teams
'500':
description: Internal Server Error
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_teams`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
/organizations/{organization}/teams/{team}:
get:
tags:
- Organization teams
operationId: get_organization_team
summary: Get an organization team
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
responses:
'200':
description: Returns the team details including members and databases
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the team
display_name:
type: string
description: The display name of the team
creator:
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
members:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two factor
authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an
authentication provider.
nullable: true
directory_managed:
type: boolean
description: >-
Whether or not the user is managed by a SSO
directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: >-
The URL to retrieve this database's branches via the
API
required:
- id
- name
- url
- branches_url
analyst_databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: >-
The URL to retrieve this database's branches via the
API
required:
- id
- name
- url
- branches_url
name:
type: string
description: The name of the team
slug:
type: string
description: The slug of the team
created_at:
type: string
description: When the team was created
updated_at:
type: string
description: When the team was last updated
description:
type: string
description: The description of the team
nullable: true
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
required:
- id
- display_name
- creator
- members
- databases
- analyst_databases
- name
- slug
- created_at
- updated_at
- description
- managed
'400':
description: Bad Request - Invalid operation or parameters
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity - Validation errors or SSO-managed teams
'500':
description: Internal Server Error
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**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_organization` |
patch:
tags:
- Organization teams
operationId: update_organization_team
summary: Update an organization team
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The new name for the team
description:
type: string
description: The new description for the team
responses:
'200':
description: 'Returns the updated team. Note: SSO-managed teams cannot be updated.'
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the team
display_name:
type: string
description: The display name of the team
creator:
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
members:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two factor
authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an
authentication provider.
nullable: true
directory_managed:
type: boolean
description: >-
Whether or not the user is managed by a SSO
directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: >-
The URL to retrieve this database's branches via the
API
required:
- id
- name
- url
- branches_url
analyst_databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: >-
The URL to retrieve this database's branches via the
API
required:
- id
- name
- url
- branches_url
name:
type: string
description: The name of the team
slug:
type: string
description: The slug of the team
created_at:
type: string
description: When the team was created
updated_at:
type: string
description: When the team was last updated
description:
type: string
description: The description of the team
nullable: true
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
required:
- id
- display_name
- creator
- members
- databases
- analyst_databases
- name
- slug
- created_at
- updated_at
- description
- managed
'400':
description: Bad Request - Invalid operation or parameters
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity - Validation errors or SSO-managed teams
'500':
description: Internal Server Error
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_teams`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
delete:
tags:
- Organization teams
operationId: delete_organization_team
summary: Delete an organization team
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
responses:
'204':
description: >-
Team deleted successfully. Note: SSO-managed teams cannot be
deleted.
headers: {}
'400':
description: Bad Request - Invalid operation or parameters
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity - Validation errors or SSO-managed teams
'500':
description: Internal Server Error
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_teams`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
/organizations/{organization}/teams/{team}/members:
get:
tags:
- Team members
operationId: list_organization_team_members
summary: List team members
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns the list of team members
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the team membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two
factor authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an
authentication provider.
nullable: true
directory_managed:
type: boolean
description: >-
Whether or not the user is managed by a SSO
directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
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
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
passwords:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: >-
List of IP addresses or CIDR ranges that can
use this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: >-
When the password was last used to execute a
query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: >-
True if the credentials connect directly to a
vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: >-
The list of hosts in each availability zone
providing direct access to a vtgate
ttl_seconds:
type: integer
description: >-
Time to live (in seconds) for the password.
The password will be invalid when TTL has
passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
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
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
username:
type: string
description: The username for the password
plain_text:
type: string
description: >-
The plain text password. Null except in the
response from the create endpoint.
nullable: true
replica:
type: boolean
description: >-
Whether or not the password is for a read
replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: >-
Whether or not the branch is a production
branch
mysql_edge_address:
type: string
description: >-
The address of the MySQL provider for the
branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
required:
- id
- user
- actor
- created_at
- updated_at
- passwords
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'400':
description: Bad Request - Invalid operation or SSO-managed team
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity - Validation errors
'500':
description: Internal Server Error
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**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_organization` |
post:
tags:
- Team members
operationId: add_organization_team_member
summary: Add a member to a team
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: The ID of the organization member to add to the team
required:
- user_id
responses:
'200':
description: Returns the created team membership
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the team membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two factor
authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an
authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
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
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
passwords:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: >-
List of IP addresses or CIDR ranges that can use
this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: >-
True if the credentials connect directly to a
vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: >-
The list of hosts in each availability zone
providing direct access to a vtgate
ttl_seconds:
type: integer
description: >-
Time to live (in seconds) for the password. The
password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
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
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
username:
type: string
description: The username for the password
plain_text:
type: string
description: >-
The plain text password. Null except in the response
from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
required:
- id
- user
- actor
- created_at
- updated_at
- passwords
'400':
description: Bad Request - Invalid operation or SSO-managed team
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity - Validation errors
'500':
description: Internal Server Error
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_teams`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
/organizations/{organization}/teams/{team}/members/{id}:
get:
tags:
- Team members
operationId: get_organization_team_member
summary: Get a team member
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
- name: id
in: path
required: true
description: The ID of the team membership or the ID of the member
schema:
type: string
responses:
'200':
description: Returns the team member details
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the team membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two factor
authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an
authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
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
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
passwords:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: >-
List of IP addresses or CIDR ranges that can use
this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: >-
True if the credentials connect directly to a
vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: >-
The list of hosts in each availability zone
providing direct access to a vtgate
ttl_seconds:
type: integer
description: >-
Time to live (in seconds) for the password. The
password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
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
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
username:
type: string
description: The username for the password
plain_text:
type: string
description: >-
The plain text password. Null except in the response
from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
required:
- id
- user
- actor
- created_at
- updated_at
- passwords
'400':
description: Bad Request - Invalid operation or SSO-managed team
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity - Validation errors
'500':
description: Internal Server Error
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**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_organization` |
delete:
tags:
- Team members
operationId: remove_organization_team_member
summary: Remove a member from a team
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
- name: id
in: path
required: true
description: The ID of the team membership or the ID of the member to remove
schema:
type: string
- name: delete_passwords
in: query
description: Whether to delete the member's passwords created through this team
schema:
type: boolean
responses:
'204':
description: >-
Member removed successfully. Note: SSO-managed teams cannot have
members removed.
headers: {}
'400':
description: Bad Request - Invalid operation or SSO-managed team
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Entity - Validation errors
'500':
description: Internal Server Error
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_teams`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
/regions:
get:
tags:
- Regions
operationId: list_public_regions
summary: List public regions
parameters:
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
'200':
description: Returns the available public PlanetScale regions
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: >-
The next page of results, or null when this is the last
page
nullable: true
prev_page:
type: integer
description: >-
The previous page number, or null when this is the first
page
nullable: true
prev_page_url:
type: string
description: >-
The previous page of results, or null when this is the
first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: The cloud provider for the region
enabled:
type: boolean
description: Whether new clusters can be created in this region
public_ip_addresses:
items:
type: string
type: array
description: List of public IP addresses for the region
display_name:
type: string
description: The name of the region
location:
type: string
description: The location of the region
slug:
type: string
description: The slug identifier for the region
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: |
Endpoint is available without authentication.
/user:
get:
tags:
- Users
operationId: get_current_user
summary: Get current user
responses:
'200':
description: Returns the user associated with this service token
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two factor
authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an authentication
provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
description: >-
Get the user associated with this service token
### Authorization
A OAuth token must have at least one of the following scopes in
order to use this API endpoint:
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| User | `read_user` |
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.
security:
- oauth2: []
x-readme:
explorer-enabled: false
servers:
- url: https://api.planetscale.com/v1
components:
requestBodies:
create_traffic_budgetBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the traffic budget
mode:
type: string
enum:
- enforce
- warn
- 'off'
description: The mode of the traffic budget
capacity:
type: integer
description: >-
The maximum capacity that can be banked, measured as a
percentage of seconds of full server usage (0-6000). Unlimited
when not set.
rate:
type: integer
description: >-
The rate at which capacity refills, as a percentage of server
resources (0-100). Unlimited when not set.
burst:
type: integer
description: >-
The maximum capacity a single query can consume, measured as a
percentage of seconds of full server usage (0-6000). Unlimited
when not set.
concurrency:
type: integer
description: >-
The percentage of available worker processes this policy can
use (0-100). Unlimited when not set.
warning_threshold:
type: integer
description: >-
A percentage of capacity, burst, or concurrency thresholds to
emit warnings for enforced budgets (0-100).
rules:
type: array
items:
type: string
description: Array of traffic rules to apply to the budget
create_backup_policyBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
enum:
- hour
- day
- week
- month
- year
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
enum:
- hour
- day
- week
- month
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0 is Sunday, 6
is Saturday
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled. 0 is the first
week, 3 is the fourth week
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
schemas:
PaginatedBackupPolicy:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0 is Sunday, 6
is Saturday
nullable: true
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled. 0 is the first
week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
BackupPolicy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0 is Sunday, 6 is
Saturday
nullable: true
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled. 0 is the first week,
3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
PaginatedBackup:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the backup
name:
type: string
description: The name of the backup
state:
type: string
enum:
- pending
- running
- success
- failed
- canceled
- ignored
description: The current state of the backup
size:
type: integer
description: The size of the backup in bytes
estimated_storage_cost:
type: number
description: The estimated storage cost of the backup
created_at:
type: string
description: When the backup was created
updated_at:
type: string
description: When the backup was last updated
started_at:
type: string
description: When the backup started
nullable: true
expires_at:
type: string
description: When the backup expires
nullable: true
completed_at:
type: string
description: When the backup completed
nullable: true
deleted_at:
type: string
description: When the backup was deleted
nullable: true
pvc_size:
type: integer
description: Size of the PVC used for the backup
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
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
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
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: >-
Whether the policy is for production or development
branches
retention_value:
type: integer
description: >-
A number value for the retention period of the backup
policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: >-
The time of day that the backup is scheduled, in HH:MM
format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0 is Sunday,
6 is Saturday
nullable: true
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled. 0 is the
first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
nullable: true
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
nullable: true
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
nullable: true
database_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
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- protected
- required
- restored_branches
- actor
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
Backup:
type: object
properties:
id:
type: string
description: The ID of the backup
name:
type: string
description: The name of the backup
state:
type: string
enum:
- pending
- running
- success
- failed
- canceled
- ignored
description: The current state of the backup
size:
type: integer
description: The size of the backup in bytes
estimated_storage_cost:
type: number
description: The estimated storage cost of the backup
created_at:
type: string
description: When the backup was created
updated_at:
type: string
description: When the backup was last updated
started_at:
type: string
description: When the backup started
nullable: true
expires_at:
type: string
description: When the backup expires
nullable: true
completed_at:
type: string
description: When the backup completed
nullable: true
deleted_at:
type: string
description: When the backup was deleted
nullable: true
pvc_size:
type: integer
description: Size of the PVC used for the backup
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
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
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
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: >-
Day of the week that the backup is scheduled. 0 is Sunday, 6 is
Saturday
nullable: true
schedule_week:
type: integer
description: >-
Week of the month that the backup is scheduled. 0 is the first
week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
nullable: true
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
nullable: true
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
nullable: true
database_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
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- protected
- required
- restored_branches
- actor
PaginatedPostgresBouncerResizeRequest:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: >-
The number of replicas per cell for the bouncer after the
resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: >-
The number of replicas per cell for the bouncer before the
resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
nullable: true
completed_at:
type: string
description: The time the bouncer resize completed
nullable: true
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
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
bouncer:
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
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
required:
- id
- state
- replicas_per_cell
- parameters
- previous_replicas_per_cell
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedPostgresClusterResizeRequest:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the branch change request
restart:
items:
type: integer
type: array
description: The ports requiring a restart when changes are applied
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
nullable: true
completed_at:
type: string
description: The time the branch change request completed
nullable: true
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
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
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: The previous SKU representing the branch cluster for display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: >-
Whether storage shrinking is enabled when autoscaling is
enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
required:
- id
- restart
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_parameters
- minimum_storage_bytes
- maximum_storage_bytes
- storage_autoscaling
- storage_shrinking
- storage_type
- storage_iops
- storage_throughput_mibs
- previous_minimum_storage_bytes
- previous_maximum_storage_bytes
- previous_storage_autoscaling
- previous_storage_shrinking
- previous_storage_type
- previous_storage_iops
- previous_storage_throughput_mibs
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PostgresClusterResizeRequest:
type: object
properties:
id:
type: string
description: The ID of the branch change request
restart:
items:
type: integer
type: array
description: The ports requiring a restart when changes are applied
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
nullable: true
completed_at:
type: string
description: The time the branch change request completed
nullable: true
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
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
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: The previous SKU representing the branch cluster for display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: Whether storage shrinking is enabled when autoscaling is enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
required:
- id
- restart
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_parameters
- minimum_storage_bytes
- maximum_storage_bytes
- storage_autoscaling
- storage_shrinking
- storage_type
- storage_iops
- storage_throughput_mibs
- previous_minimum_storage_bytes
- previous_maximum_storage_bytes
- previous_storage_autoscaling
- previous_storage_shrinking
- previous_storage_type
- previous_storage_iops
- previous_storage_throughput_mibs
PaginatedDatabaseBranch:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
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
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
DatabaseBranch:
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
PaginatedSchemaLintError:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
lint_error:
type: string
description: Code representing the type of error
subject_type:
type: string
enum:
- table
- vschema
- routing_rules
description: The subject for the errors
keyspace_name:
type: string
description: The keyspace of the schema with the error
table_name:
type: string
description: The table with the error
error_description:
type: string
description: A description for the error that occurred
docs_url:
type: string
description: A link to the documentation related to the error
column_name:
type: string
description: The column in a table relevant to the error
foreign_key_column_names:
items:
type: string
type: array
description: A list of invalid foreign key columns in a table
auto_increment_column_names:
items:
type: string
type: array
description: A list of invalid auto-incremented columns
charset_name:
type: string
description: The charset of the schema
engine_name:
type: string
description: The engine of the schema
vindex_name:
type: string
description: The name of the vindex for the schema
json_path:
type: string
description: The path for an invalid JSON column
check_constraint_name:
type: string
description: The name of the invalid check constraint
enum_value:
type: string
description: The name of the invalid enum value
partitioning_type:
type: string
description: The name of the invalid partitioning type
partition_name:
type: string
description: The name of the invalid partition in the schema
required:
- lint_error
- subject_type
- keyspace_name
- table_name
- error_description
- docs_url
- column_name
- foreign_key_column_names
- auto_increment_column_names
- charset_name
- engine_name
- vindex_name
- json_path
- check_constraint_name
- enum_value
- partitioning_type
- partition_name
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PostgresClusterExtension:
type: object
properties:
id:
type: string
description: The ID of the extension
name:
type: string
description: The name of the extension
description:
type: string
description: The description of the extension
internal:
type: boolean
description: The internal state of the extension
shared_preload_allowed:
type: boolean
description: Whether the extension can be added to shared_preload_libraries
url:
type: string
description: The URL of the extension
available:
type: boolean
description: Whether the extension is available on the current cluster image
unavailable_reason:
type: string
description: >-
The reason the extension is unavailable (e.g.,
'container_upgrade_required')
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
namespace:
type: string
enum:
- patroni
- pgconf
- pgbouncer
description: The namespace of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
extension:
type: boolean
description: Configures an extension
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- seconds
- select
- string
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
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
updated_at:
type: string
description: When the parameter was last updated
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
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options 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
- name
- display_name
- namespace
- category
- description
- extension
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
required:
- id
- name
- description
- internal
- shared_preload_allowed
- url
- available
- unavailable_reason
- parameters
PostgresClusterParameter:
type: object
properties:
id:
type: string
description: The ID of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
namespace:
type: string
enum:
- patroni
- pgconf
- pgbouncer
description: The namespace of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
extension:
type: boolean
description: Configures an extension
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- seconds
- select
- string
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
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
updated_at:
type: string
description: When the parameter was last updated
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
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options 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
- name
- display_name
- namespace
- category
- description
- extension
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
PaginatedDatabaseBranchKeyspace:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
config_change_in_progress:
type: boolean
description: Is the keyspace undergoing a config change
ready:
type: boolean
description: Is the keyspace provisioned and serving traffic
metal:
type: boolean
description: Is the keyspace running on metal instances
default:
type: boolean
description: Is this the default keyspace for the branch
imported:
type: boolean
description: Is this keyspace used in an import
vector_pool_allocation:
type: number
description: Percentage of buffer pool memory allocated to vector indexes
nullable: true
node_ttl_strategy:
type: string
enum:
- node_ttl_follow_maintenance
- node_ttl_always
- node_ttl_off
description: Controls when node TTL drains are allowed
replication_durability_constraints:
type: object
properties:
strategy:
type: string
enum:
- available
- lag
- always
description: The replication durability strategy
nullable: true
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_pending
- config_change_in_progress
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
DatabaseBranchKeyspace:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
config_change_in_progress:
type: boolean
description: Is the keyspace undergoing a config change
ready:
type: boolean
description: Is the keyspace provisioned and serving traffic
metal:
type: boolean
description: Is the keyspace running on metal instances
default:
type: boolean
description: Is this the default keyspace for the branch
imported:
type: boolean
description: Is this keyspace used in an import
vector_pool_allocation:
type: number
description: Percentage of buffer pool memory allocated to vector indexes
nullable: true
node_ttl_strategy:
type: string
enum:
- node_ttl_follow_maintenance
- node_ttl_always
- node_ttl_off
description: Controls when node TTL drains are allowed
replication_durability_constraints:
type: object
properties:
strategy:
type: string
enum:
- available
- lag
- always
description: The replication durability strategy
nullable: true
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_pending
- config_change_in_progress
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
PaginatedDatabaseBranchPassword:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: >-
True if the credentials connect directly to a vtgate,
bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: >-
The list of hosts in each availability zone providing direct
access to a vtgate
ttl_seconds:
type: integer
description: >-
Time to live (in seconds) for the password. The password will
be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
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
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
username:
type: string
description: The username for the password
plain_text:
type: string
description: >-
The plain text password. Null except in the response from the
create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
DatabaseBranchPassword:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: >-
True if the credentials connect directly to a vtgate, bypassing load
balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: >-
The list of hosts in each availability zone providing direct access
to a vtgate
ttl_seconds:
type: integer
description: >-
Time to live (in seconds) for the password. The password will be
invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
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
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
username:
type: string
description: The username for the password
plain_text:
type: string
description: >-
The plain text password. Null except in the response from the create
endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
PaginatedPostgresClusterCidr:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
nullable: true
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
- schema
- role
- cidrs
- created_at
- updated_at
- deleted_at
- actor
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PostgresClusterCidr:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
nullable: true
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
- schema
- role
- cidrs
- created_at
- updated_at
- deleted_at
- actor
PaginatedDatabase:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
branches_count:
type: integer
description: The total number of database branches
open_schema_recommendations_count:
type: integer
description: The total number of schema recommendations
development_branches_count:
type: integer
description: The total number of database development branches
production_branches_count:
type: integer
description: The total number of database production branches
issues_count:
type: integer
description: The total number of ongoing issues within a database
nullable: true
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: If the database has reached its backup restored branch limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
nullable: true
finished_at:
type: string
description: When the import finished
nullable: true
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
required:
- hostname
- port
- database
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
nullable: true
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
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: >-
Whether an approval is required to deploy schema changes to
this database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
config_changing:
type: boolean
description: True if a config change is in progress
config_change_queued:
type: boolean
description: True if a config change is queued for maintenance window
allow_data_branching:
type: boolean
description: Whether seeding branches with data is enabled for all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: >-
Whether to automatically manage Rails migrations during deploy
requests.
nullable: true
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data.
nullable: true
migration_framework:
type: string
description: Framework used for applying migrations.
nullable: true
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- resizing
- resize_queued
- config_changing
- config_change_queued
- allow_data_branching
- foreign_keys_enabled
- restrict_branch_region
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- created_at
- updated_at
- schema_last_updated_at
- kind
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
Database:
type: object
properties:
id:
type: string
description: The ID of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
branches_count:
type: integer
description: The total number of database branches
open_schema_recommendations_count:
type: integer
description: The total number of schema recommendations
development_branches_count:
type: integer
description: The total number of database development branches
production_branches_count:
type: integer
description: The total number of database production branches
issues_count:
type: integer
description: The total number of ongoing issues within a database
nullable: true
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: If the database has reached its backup restored branch limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
nullable: true
finished_at:
type: string
description: When the import finished
nullable: true
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
required:
- hostname
- port
- database
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
nullable: true
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
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: >-
Whether an approval is required to deploy schema changes to this
database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
config_changing:
type: boolean
description: True if a config change is in progress
config_change_queued:
type: boolean
description: True if a config change is queued for maintenance window
allow_data_branching:
type: boolean
description: Whether seeding branches with data is enabled for all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: >-
Whether to automatically manage Rails migrations during deploy
requests.
nullable: true
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data.
nullable: true
migration_framework:
type: string
description: Framework used for applying migrations.
nullable: true
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- resizing
- resize_queued
- config_changing
- config_change_queued
- allow_data_branching
- foreign_keys_enabled
- restrict_branch_region
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- created_at
- updated_at
- schema_last_updated_at
- kind
PaginatedPlanetscaleRegion:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
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
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedDatabaseBranchReadOnlyRegion:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the read-only region
display_name:
type: string
description: The name of the read-only region
created_at:
type: string
description: When the read-only region was created
updated_at:
type: string
description: When the read-only region was last updated
ready_at:
type: string
description: When the read-only region was ready to serve queries
nullable: true
ready:
type: boolean
description: Whether or not the read-only region 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
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
required:
- id
- display_name
- created_at
- updated_at
- ready_at
- ready
- actor
- region
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
ThrottlerConfigurations:
type: object
properties:
keyspaces:
items:
type: string
type: array
description: >-
Keyspaces that are eligible for throttler configuration in the
configurable resource (database or deploy request)
configurable:
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
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: >-
A throttler ratio between 0 and 95 that applies to migrations
in this specific keyspace
required:
- keyspace_name
- ratio
required:
- keyspaces
- configurable
- configurations
PaginatedBranchMaintenanceSchedule:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the maintenance schedule
name:
type: string
description: The display name of the maintenance schedule
created_at:
type: string
description: When the maintenance schedule was created
updated_at:
type: string
description: When the maintenance schedule was last updated
last_window_datetime:
type: string
description: When the last maintenance window started
next_window_datetime:
type: string
description: When the next maintenance window is scheduled
duration:
type: integer
description: The duration of the maintenance window in hours
day:
type: integer
description: Day of the week (0 = Sunday, 6 = Saturday, 7 = every day)
hour:
type: integer
description: Hour of the day in UTC (0-23)
week:
type: integer
description: Week of the month for monthly schedules (0-3)
frequency_value:
type: integer
description: The frequency value of the maintenance schedule
frequency_unit:
type: string
enum:
- day
- week
- month
- once
description: The frequency unit of the maintenance schedule
enabled:
type: boolean
description: Whether the maintenance schedule is enabled
expires_at:
type: string
description: When a one-time maintenance schedule expires
nullable: true
deadline_at:
type: string
description: The deadline for a required maintenance schedule
nullable: true
required:
type: boolean
description: Whether the maintenance schedule is required
pending_vitess_version_update:
type: boolean
description: Whether there is a pending Vitess version update
pending_vitess_version:
type: string
description: The pending Vitess version, if any
nullable: true
pending_mysql_version_update:
type: boolean
description: Whether there is a pending MySQL version update
pending_mysql_version:
type: string
description: The pending MySQL version, if any
nullable: true
required:
- id
- name
- created_at
- updated_at
- last_window_datetime
- next_window_datetime
- duration
- day
- hour
- week
- frequency_value
- frequency_unit
- enabled
- expires_at
- deadline_at
- required
- pending_vitess_version_update
- pending_vitess_version
- pending_mysql_version_update
- pending_mysql_version
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
BranchMaintenanceSchedule:
type: object
properties:
id:
type: string
description: The ID of the maintenance schedule
name:
type: string
description: The display name of the maintenance schedule
created_at:
type: string
description: When the maintenance schedule was created
updated_at:
type: string
description: When the maintenance schedule was last updated
last_window_datetime:
type: string
description: When the last maintenance window started
next_window_datetime:
type: string
description: When the next maintenance window is scheduled
duration:
type: integer
description: The duration of the maintenance window in hours
day:
type: integer
description: Day of the week (0 = Sunday, 6 = Saturday, 7 = every day)
hour:
type: integer
description: Hour of the day in UTC (0-23)
week:
type: integer
description: Week of the month for monthly schedules (0-3)
frequency_value:
type: integer
description: The frequency value of the maintenance schedule
frequency_unit:
type: string
enum:
- day
- week
- month
- once
description: The frequency unit of the maintenance schedule
enabled:
type: boolean
description: Whether the maintenance schedule is enabled
expires_at:
type: string
description: When a one-time maintenance schedule expires
nullable: true
deadline_at:
type: string
description: The deadline for a required maintenance schedule
nullable: true
required:
type: boolean
description: Whether the maintenance schedule is required
pending_vitess_version_update:
type: boolean
description: Whether there is a pending Vitess version update
pending_vitess_version:
type: string
description: The pending Vitess version, if any
nullable: true
pending_mysql_version_update:
type: boolean
description: Whether there is a pending MySQL version update
pending_mysql_version:
type: string
description: The pending MySQL version, if any
nullable: true
required:
- id
- name
- created_at
- updated_at
- last_window_datetime
- next_window_datetime
- duration
- day
- hour
- week
- frequency_value
- frequency_unit
- enabled
- expires_at
- deadline_at
- required
- pending_vitess_version_update
- pending_vitess_version
- pending_mysql_version_update
- pending_mysql_version
PaginatedBranchMaintenanceWindow:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the maintenance window
created_at:
type: string
description: When the maintenance window was created
updated_at:
type: string
description: When the maintenance window was last updated
started_at:
type: string
description: When the maintenance window started
nullable: true
finished_at:
type: string
description: When the maintenance window finished
nullable: true
required:
- id
- created_at
- updated_at
- started_at
- finished_at
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedOauthApplication:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the app
name:
type: string
description: The name of the app
redirect_uri:
type: string
description: The redirect URI of the OAuth application
domain:
type: string
description: >-
The domain of the OAuth application. Used for verification of
a valid redirect uri
created_at:
type: string
description: When the OAuth application was created
updated_at:
type: string
description: When the OAuth application was last updated
scopes:
type: string
description: >-
The scopes that the OAuth application requires on a user
account, as a space-separated string
avatar:
type: string
description: The image source for the OAuth application's avatar
client_id:
type: string
description: The OAuth application's unique client id
tokens:
type: integer
description: The number of tokens issued by the OAuth application
dcr:
type: boolean
description: >-
Whether the OAuth application was created via Dynamic Client
Registration
single_org_authorization:
type: boolean
description: >-
Whether the OAuth application is limited to authorizing a
single organization
scopes_by_resource:
type: object
additionalProperties: true
description: >-
Scopes grouped by resource type (database, organization,
branch, user) with scope, description, and admin flag
all_scopes_by_resource:
type: object
additionalProperties: true
description: >-
All available scopes grouped by resource type with scope,
description, selected, and admin flags
required:
- id
- name
- redirect_uri
- domain
- created_at
- updated_at
- scopes
- avatar
- client_id
- tokens
- dcr
- single_org_authorization
- scopes_by_resource
- all_scopes_by_resource
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
OauthApplication:
type: object
properties:
id:
type: string
description: The ID of the app
name:
type: string
description: The name of the app
redirect_uri:
type: string
description: The redirect URI of the OAuth application
domain:
type: string
description: >-
The domain of the OAuth application. Used for verification of a
valid redirect uri
created_at:
type: string
description: When the OAuth application was created
updated_at:
type: string
description: When the OAuth application was last updated
scopes:
type: string
description: >-
The scopes that the OAuth application requires on a user account, as
a space-separated string
avatar:
type: string
description: The image source for the OAuth application's avatar
client_id:
type: string
description: The OAuth application's unique client id
tokens:
type: integer
description: The number of tokens issued by the OAuth application
dcr:
type: boolean
description: >-
Whether the OAuth application was created via Dynamic Client
Registration
single_org_authorization:
type: boolean
description: >-
Whether the OAuth application is limited to authorizing a single
organization
scopes_by_resource:
type: object
additionalProperties: true
description: >-
Scopes grouped by resource type (database, organization, branch,
user) with scope, description, and admin flag
all_scopes_by_resource:
type: object
additionalProperties: true
description: >-
All available scopes grouped by resource type with scope,
description, selected, and admin flags
required:
- id
- name
- redirect_uri
- domain
- created_at
- updated_at
- scopes
- avatar
- client_id
- tokens
- dcr
- single_org_authorization
- scopes_by_resource
- all_scopes_by_resource
PaginatedServiceToken:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: >-
The ID of the actor on whose behalf the service token was
created
nullable: true
actor_display_name:
type: string
description: >-
The name of the actor on whose behalf the service token was
created
nullable: true
actor_type:
type: string
description: >-
The type of the actor on whose behalf the service token was
created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: >-
The name of the resource the service token access gives
access to
resource_id:
type: string
description: >-
The ID of the resource the service token access gives
access to
resource_type:
type: string
description: >-
The type of the resource the service token access gives
access to
resource:
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
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: >-
the name of the organization the branch belongs
to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
ServiceToken:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
nullable: true
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
nullable: true
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: >-
The name of the resource the service token access gives access
to
resource_id:
type: string
description: >-
The ID of the resource the service token access gives access
to
resource_type:
type: string
description: >-
The type of the resource the service token access gives access
to
resource:
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
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
PaginatedOrganizationMembership:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two factor
authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an authentication
provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
required:
- id
- user
- role
- created_at
- updated_at
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
OrganizationMembership:
type: object
properties:
id:
type: string
description: The ID of the membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an authentication
provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
required:
- id
- user
- role
- created_at
- updated_at
PaginatedOrganization:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the organization
name:
type: string
description: The name of the organization
billing_email:
type: string
description: The billing email of the organization
created_at:
type: string
description: When the organization was created
updated_at:
type: string
description: When the organization was last updated
plan:
type: string
description: The billing plan of the organization
valid_billing_info:
type: boolean
description: Whether or not the organization's billing information is valid
sso:
type: boolean
description: Whether or not SSO is enabled on the organization
sso_directory:
type: boolean
description: Whether or not the organization uses an SSO directory
single_tenancy:
type: boolean
description: Whether or not the organization has single tenancy enabled
managed_tenancy:
type: boolean
description: Whether or not the organization has managed tenancy enabled
has_past_due_invoices:
type: boolean
description: Whether or not the organization has past due billing invoices.
nullable: true
database_count:
type: integer
description: The number of databases in the organization
sso_portal_url:
type: string
description: The URL of the organization's SSO portal.
nullable: true
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: >-
Whether or not the IdP provider is be responsible for managing
roles in PlanetScale
invoice_budget_amount:
type: string
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: integer
description: The keyspace shard limit for the organization
has_card:
type: boolean
description: Whether or not the organization has a payment method on file
payment_info_required:
type: boolean
description: Whether or not the organization requires payment information
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- database_count
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
Organization:
type: object
properties:
id:
type: string
description: The ID for the organization
name:
type: string
description: The name of the organization
billing_email:
type: string
description: The billing email of the organization
created_at:
type: string
description: When the organization was created
updated_at:
type: string
description: When the organization was last updated
plan:
type: string
description: The billing plan of the organization
valid_billing_info:
type: boolean
description: Whether or not the organization's billing information is valid
sso:
type: boolean
description: Whether or not SSO is enabled on the organization
sso_directory:
type: boolean
description: Whether or not the organization uses an SSO directory
single_tenancy:
type: boolean
description: Whether or not the organization has single tenancy enabled
managed_tenancy:
type: boolean
description: Whether or not the organization has managed tenancy enabled
has_past_due_invoices:
type: boolean
description: Whether or not the organization has past due billing invoices.
nullable: true
database_count:
type: integer
description: The number of databases in the organization
sso_portal_url:
type: string
description: The URL of the organization's SSO portal.
nullable: true
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: >-
Whether or not the IdP provider is be responsible for managing roles
in PlanetScale
invoice_budget_amount:
type: string
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: integer
description: The keyspace shard limit for the organization
has_card:
type: boolean
description: Whether or not the organization has a payment method on file
payment_info_required:
type: boolean
description: Whether or not the organization requires payment information
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- database_count
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
ClusterSizeSkuSerializer:
type: object
properties:
name:
type: string
description: The name of the cluster SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The number of CPUs
storage:
type: integer
description: The amount of storage in bytes
nullable: true
ram:
type: integer
description: The amount of memory in bytes
metal:
type: boolean
description: Whether or not the cluster SKU is Metal
enabled:
type: boolean
description: Whether or not the cluster SKU is enabled for the organization
provider:
type: string
description: The provider of the cluster SKU (nil, AWS or GCP)
nullable: true
default_vtgate:
type: string
description: The default vtgate size for the cluster SKU
default_vtgate_rate:
type: number
description: The default vtgate rate for the cluster SKU
nullable: true
replica_rate:
type: number
description: The replica rate for the cluster SKU
nullable: true
rate:
type: number
description: The rate for the cluster SKU
nullable: true
sort_order:
type: integer
description: The sort order of the cluster SKU
architecture:
type: string
description: The architecture of the cluster SKU (null, x86_64 or arm64)
nullable: true
development:
type: boolean
description: Whether or not the cluster SKU is a development SKU
production:
type: boolean
description: Whether or not the cluster SKU is a production SKU
required:
- name
- display_name
- cpu
- storage
- ram
- metal
- enabled
- provider
- default_vtgate
- default_vtgate_rate
- sort_order
- development
- production
PaginatedAuditLogEvent:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
has_next:
type: boolean
description: Whether there is a next page of results
has_prev:
type: boolean
description: Whether there is a previous page of results
cursor_start:
type: string
description: >-
The ID of the first object in the current results, or null when
there are no results
nullable: true
cursor_end:
type: string
description: >-
The ID of the last object in the current results, or null when there
are no results
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the audit log
actor_id:
type: string
description: The ID of the actor
nullable: true
actor_type:
type: string
description: The type of the actor. Such as 'User' or 'ServiceToken'
nullable: true
auditable_id:
type: string
description: The ID of the auditable object
nullable: true
auditable_type:
type: string
description: >-
The type of the auditable. Such as 'Organization' or
'Database'
nullable: true
target_id:
type: string
description: The ID of the target
nullable: true
target_type:
type: string
description: >-
The type of the target. Such as 'DatabaseBranch' or
'DatabaseBranchPassword'
nullable: true
location:
type: string
description: The location of the actor based on their IP address
nullable: true
target_display_name:
type: string
description: The name of the target
nullable: true
audit_action:
type: string
description: The action that was taken
action:
type: string
description: The action that was taken
actor_display_name:
type: string
description: The name of the actor
auditable_display_name:
type: string
description: The name of the auditable object
remote_ip:
type: string
description: The IP address of the actor
nullable: true
created_at:
type: string
description: When the audit log was created
updated_at:
type: string
description: When the audit log was last updated
metadata:
type: object
additionalProperties: true
description: Additional metadata containing details about the change
nullable: true
required:
- id
- actor_id
- actor_type
- auditable_id
- auditable_type
- target_id
- target_type
- location
- target_display_name
- audit_action
- action
- actor_display_name
- auditable_display_name
- remote_ip
- created_at
- updated_at
- metadata
required:
- type
- has_next
- has_prev
- cursor_start
- cursor_end
- data
PostgresBouncerResizeRequest:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer after the resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer before the resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
nullable: true
completed_at:
type: string
description: The time the bouncer resize completed
nullable: true
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
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
bouncer:
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
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
required:
- id
- state
- replicas_per_cell
- parameters
- previous_replicas_per_cell
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
PaginatedPostgresBouncer:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer
name:
type: string
description: The name of the bouncer
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The instance type the bouncer targets
replicas_per_cell:
type: integer
description: The count of replicas in each cell
created_at:
type: string
description: When the bouncer was created
updated_at:
type: string
description: When the bouncer was updated
deleted_at:
type: string
description: When the bouncer was deleted
nullable: true
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
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
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
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:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
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
updated_at:
type: string
description: When the parameter was last updated
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
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options 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
- step
- url
- options
- actor
required:
- id
- name
- sku
- target
- replicas_per_cell
- created_at
- updated_at
- deleted_at
- actor
- branch
- parameters
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PostgresBouncer:
type: object
properties:
id:
type: string
description: The ID of the bouncer
name:
type: string
description: The name of the bouncer
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The instance type the bouncer targets
replicas_per_cell:
type: integer
description: The count of replicas in each cell
created_at:
type: string
description: When the bouncer was created
updated_at:
type: string
description: When the bouncer was updated
deleted_at:
type: string
description: When the bouncer was deleted
nullable: true
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
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
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
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:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
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
updated_at:
type: string
description: When the parameter was last updated
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
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options 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
- step
- url
- options
- actor
required:
- id
- name
- sku
- target
- replicas_per_cell
- created_at
- updated_at
- deleted_at
- actor
- branch
- parameters
PaginatedPostgresRole:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
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
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
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PostgresRole:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
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
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
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- 'off'
- warn
- 'on'
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
PaginatedQueryPatternsDownload:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
has_next:
type: boolean
description: Whether there is a next page of results
has_prev:
type: boolean
description: Whether there is a previous page of results
cursor_start:
type: string
description: >-
The ID of the first object in the current results, or null when
there are no results
nullable: true
cursor_end:
type: string
description: >-
The ID of the last object in the current results, or null when there
are no results
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
nullable: true
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
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
- state
- created_at
- finished_at
- url
- download_url
- actor
required:
- type
- has_next
- has_prev
- cursor_start
- cursor_end
- data
QueryPatternsDownload:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
nullable: true
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
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
- state
- created_at
- finished_at
- url
- download_url
- actor
PaginatedPublicPlanetscaleRegionSerializer:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: The cloud provider for the region
enabled:
type: boolean
description: Whether new clusters can be created in this region
public_ip_addresses:
items:
type: string
type: array
description: List of public IP addresses for the region
display_name:
type: string
description: The name of the region
location:
type: string
description: The location of the region
slug:
type: string
description: The slug identifier for the region
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedSchemaRecommendation:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the schema recommendation
html_url:
type: string
description: The URL to the schema recommendation in the app
title:
type: string
description: The title of the schema recommendation
table_name:
type: string
description: The name of the table the recommendation applies to
keyspace:
type: string
description: The keyspace the recommendation applies to
ddl_statement:
type: string
description: The DDL statement to apply the recommendation
number:
type: integer
description: The number of the schema recommendation
state:
type: string
enum:
- open
- applied
- dismissed
- stale
description: The state of the recommendation
recommendation_type:
type: string
enum:
- unused_table
- unused_index
- duplicate_index
- sequence_overflow
- sequence_overflow_foreign_key
- new_index
- encoding_upgrade
- bloated_table
- bloated_index
description: The type of recommendation
created_at:
type: string
description: When the recommendation was created
updated_at:
type: string
description: When the recommendation was last updated
applied_at:
type: string
description: When the recommendation was applied
nullable: true
dismissed_at:
type: string
description: When the recommendation was dismissed
nullable: true
closed_by_deploy_request:
type: object
properties:
id:
type: string
description: The ID of the deploy request
branch_id:
type: string
description: The ID of the branch
number:
type: integer
description: The number of the deploy request
required:
- id
- branch_id
- number
nullable: true
dismissed_by:
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
required:
- id
- html_url
- title
- table_name
- keyspace
- ddl_statement
- number
- state
- recommendation_type
- created_at
- updated_at
- applied_at
- dismissed_at
- closed_by_deploy_request
- dismissed_by
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
SchemaRecommendation:
type: object
properties:
id:
type: string
description: The ID of the schema recommendation
html_url:
type: string
description: The URL to the schema recommendation in the app
title:
type: string
description: The title of the schema recommendation
table_name:
type: string
description: The name of the table the recommendation applies to
keyspace:
type: string
description: The keyspace the recommendation applies to
ddl_statement:
type: string
description: The DDL statement to apply the recommendation
number:
type: integer
description: The number of the schema recommendation
state:
type: string
enum:
- open
- applied
- dismissed
- stale
description: The state of the recommendation
recommendation_type:
type: string
enum:
- unused_table
- unused_index
- duplicate_index
- sequence_overflow
- sequence_overflow_foreign_key
- new_index
- encoding_upgrade
- bloated_table
- bloated_index
description: The type of recommendation
created_at:
type: string
description: When the recommendation was created
updated_at:
type: string
description: When the recommendation was last updated
applied_at:
type: string
description: When the recommendation was applied
nullable: true
dismissed_at:
type: string
description: When the recommendation was dismissed
nullable: true
closed_by_deploy_request:
type: object
properties:
id:
type: string
description: The ID of the deploy request
branch_id:
type: string
description: The ID of the branch
number:
type: integer
description: The number of the deploy request
required:
- id
- branch_id
- number
nullable: true
dismissed_by:
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
required:
- id
- html_url
- title
- table_name
- keyspace
- ddl_statement
- number
- state
- recommendation_type
- created_at
- updated_at
- applied_at
- dismissed_at
- closed_by_deploy_request
- dismissed_by
PaginatedTrafficBudget:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic budget
name:
type: string
description: The name of the budget
mode:
type: string
enum:
- enforce
- warn
- 'off'
description: The mode of the budget
capacity:
type: number
description: >-
The maximum capacity that can be banked, measured as a
percentage of seconds of full server usage (0-6000). Unlimited
when not set.
nullable: true
rate:
type: number
description: >-
The rate at which capacity refills, as a percentage of server
resources (0-100). Unlimited when not set.
nullable: true
burst:
type: number
description: >-
The maximum capacity a single query can consume, measured as a
percentage of seconds of full server usage (0-6000). Unlimited
when not set.
nullable: true
concurrency:
type: number
description: >-
The percentage of available worker processes this policy can
use (0-100). Unlimited when not set.
nullable: true
warning_threshold:
type: number
description: >-
A percentage of capacity, burst, or concurrency thresholds to
emit warnings for enforced budgets (0-100).
nullable: true
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
rules:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
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
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
created_at:
type: string
description: When the budget was created
updated_at:
type: string
description: When the budget was updated
required:
- id
- name
- mode
- actor
- rules
- created_at
- updated_at
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
TrafficBudget:
type: object
properties:
id:
type: string
description: The ID of the traffic budget
name:
type: string
description: The name of the budget
mode:
type: string
enum:
- enforce
- warn
- 'off'
description: The mode of the budget
capacity:
type: number
description: >-
The maximum capacity that can be banked, measured as a percentage of
seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
rate:
type: number
description: >-
The rate at which capacity refills, as a percentage of server
resources (0-100). Unlimited when not set.
nullable: true
burst:
type: number
description: >-
The maximum capacity a single query can consume, measured as a
percentage of seconds of full server usage (0-6000). Unlimited when
not set.
nullable: true
concurrency:
type: number
description: >-
The percentage of available worker processes this policy can use
(0-100). Unlimited when not set.
nullable: true
warning_threshold:
type: number
description: >-
A percentage of capacity, burst, or concurrency thresholds to emit
warnings for enforced budgets (0-100).
nullable: true
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
rules:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
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
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
created_at:
type: string
description: When the budget was created
updated_at:
type: string
description: When the budget was updated
required:
- id
- name
- mode
- actor
- rules
- created_at
- updated_at
TrafficRule:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
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
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
User:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
PaginatedWorkflow:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
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
verify_data_by:
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
reversed_by:
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
switch_replicas_by:
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
switch_primaries_by:
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
cancelled_by:
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
completed_by:
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
retried_by:
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
cutover_by:
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
reversed_cutover_by:
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
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
source_keyspace:
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
target_keyspace:
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
global_keyspace:
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
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
Workflow:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
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
verify_data_by:
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
reversed_by:
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
switch_replicas_by:
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
switch_primaries_by:
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
cancelled_by:
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
completed_by:
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
retried_by:
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
cutover_by:
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
reversed_cutover_by:
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
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
source_keyspace:
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
target_keyspace:
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
global_keyspace:
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
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
PaginatedDeployRequestReview:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the review
body:
type: string
description: The text body of the review
html_body:
type: string
description: The HTML body of the review
state:
type: string
enum:
- commented
- approved
description: Whether the review is a comment or approval
created_at:
type: string
description: When the review was created
updated_at:
type: string
description: When the review was last updated
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
- body
- html_body
- state
- created_at
- updated_at
- actor
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
DeployRequestReview:
type: object
properties:
id:
type: string
description: The ID of the review
body:
type: string
description: The text body of the review
html_body:
type: string
description: The HTML body of the review
state:
type: string
enum:
- commented
- approved
description: Whether the review is a comment or approval
created_at:
type: string
description: When the review was created
updated_at:
type: string
description: When the review was last updated
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
- body
- html_body
- state
- created_at
- updated_at
- actor
PaginatedDatabaseDeployRequest:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
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
closed_by:
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
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
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
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: >-
Whether or not the branch the deploy request will be merged
into is sharded
into_branch_shard_count:
type: integer
description: >-
The number of shards the branch the deploy request will be
merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once deployment is
finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch
once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: >-
The name of the base branch the deployment will be merged
into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with this
deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the
deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy error,
if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the deploy
operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable of
dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation was
last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation summary
keyspace_name:
type: string
description: >-
The keyspace modified by the deploy operation
summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: >-
The percent completion for the deploy operation
summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the deploy
operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy
operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation
summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: >-
Names of foreign keys removed by this operation
summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by the
deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the
deploy operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is
capable of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the deploy
operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being
performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: >-
The percent completion for the deploy
operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: >-
Schema lint errors preventing the deployment from
completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: >-
The request to revert the schema operations in this
deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is
currently paused
queue_pause_reason:
type: string
description: >-
A human-readable reason the deploy queue is paused, if
known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
DatabaseDeployRequest:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
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
closed_by:
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
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
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
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: >-
Whether or not the branch the deploy request will be merged into is
sharded
into_branch_shard_count:
type: integer
description: >-
The number of shards the branch the deploy request will be merged
into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once deployment is
finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch once
deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the deploy
operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy error, if
present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the deploy
operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable of dropping
data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy operation
is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy operation
was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation was last
used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the deploy
operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the deploy
operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy operation
summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation summary
was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by the
deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the deploy
operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is capable of
dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy operation
summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the deploy
operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is currently
paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
Deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch once
deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the deploy
operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy error, if
present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable of dropping
data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy operation is
currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy operation was
recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the deploy
operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the deploy operation
summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation summary was
last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by the deploy
operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the deploy
operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is capable of
dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy operation
summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the deploy operation
summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the deploy
operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
PaginatedDeployOperation:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the deploy
operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy error, if
present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable of dropping
data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy operation is
currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy operation was
recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedDeployment:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: >-
Whether or not to automatically cutover once deployment is
finished
auto_delete_branch:
type: boolean
description: >-
Whether or not to automatically delete the head branch once
deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: >-
The number of the deploy request associated with this
deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: >-
The estimated seconds until completion for the deploy
operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: >-
A link to documentation explaining the deploy error, if
present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the deploy
operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation is capable of
dropping data
table_locked:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation is currently locked
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation was recently used
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation was last
used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the deploy
operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: >-
A syntax-highlighted DDL statement for the deploy
operation summary
table_name:
type: string
description: >-
The name of the table modifed by the deploy operation
summary
table_recently_used_at:
type: string
description: >-
When the table modified by the deploy operation summary
was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: >-
The number of shards in the keyspace modified by the
deploy operation summary
shard_names:
items:
type: string
type: array
description: >-
Names of shards in the keyspace modified by the deploy
operation summary
can_drop_data:
type: boolean
description: >-
Whether or not the deploy operation summary is capable
of dropping data
table_recently_used:
type: boolean
description: >-
Whether or not the table modified by the deploy
operation summary was recently used
sharded:
type: boolean
description: >-
Whether or not the keyspace modified by the deploy
operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: >-
The shard the deploy operation is being performed
on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: >-
The estimated seconds until completion for the
deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
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
cutover_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
cancelled_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
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: >-
Whether the deploy queue for the target branch is currently
paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedDatabaseWebhook:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
nullable: true
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
DatabaseWebhook:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
nullable: true
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
PaginatedLineItem:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the line item
subtotal:
type: number
description: The total for the line item
description:
type: string
description: The description for the line item
metric_name:
type: string
description: The name of the billable item
database_id:
type: string
description: The ID for the billed database
database_name:
type: string
description: The name for the billed database
resource:
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
required:
- id
- subtotal
- description
- metric_name
- database_id
- database_name
- resource
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedInvoice:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the invoice
total:
type: string
description: >-
The total amount of the invoice, as a stringified decimal to
preserve precision
billing_period_start:
type: string
description: Start of the billing period
billing_period_end:
type: string
description: End of the billing period
paid:
type: boolean
description: Whether the invoice has been paid
overdue:
type: boolean
description: Whether the invoice is past due and unpaid
required:
- id
- total
- billing_period_start
- billing_period_end
- paid
- overdue
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
Invoice:
type: object
properties:
id:
type: string
description: The ID of the invoice
total:
type: string
description: >-
The total amount of the invoice, as a stringified decimal to
preserve precision
billing_period_start:
type: string
description: Start of the billing period
billing_period_end:
type: string
description: End of the billing period
paid:
type: boolean
description: Whether the invoice has been paid
overdue:
type: boolean
description: Whether the invoice is past due and unpaid
required:
- id
- total
- billing_period_start
- billing_period_end
- paid
- overdue
PaginatedOrganizationTeamMembership:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the team membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two factor
authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an authentication
provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
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
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
passwords:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: >-
List of IP addresses or CIDR ranges that can use this
password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: >-
True if the credentials connect directly to a vtgate,
bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: >-
The list of hosts in each availability zone providing
direct access to a vtgate
ttl_seconds:
type: integer
description: >-
Time to live (in seconds) for the password. The password
will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
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
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
username:
type: string
description: The username for the password
plain_text:
type: string
description: >-
The plain text password. Null except in the response
from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
required:
- id
- user
- actor
- created_at
- updated_at
- passwords
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
OrganizationTeamMembership:
type: object
properties:
id:
type: string
description: The ID of the team membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an authentication
provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
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
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
passwords:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: >-
True if the credentials connect directly to a vtgate,
bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: >-
The list of hosts in each availability zone providing direct
access to a vtgate
ttl_seconds:
type: integer
description: >-
Time to live (in seconds) for the password. The password will
be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
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
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
username:
type: string
description: The username for the password
plain_text:
type: string
description: >-
The plain text password. Null except in the response from the
create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
required:
- id
- user
- actor
- created_at
- updated_at
- passwords
PaginatedOrganizationTeam:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the team
display_name:
type: string
description: The display name of the team
creator:
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
members:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two factor
authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an authentication
provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
analyst_databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
name:
type: string
description: The name of the team
slug:
type: string
description: The slug of the team
created_at:
type: string
description: When the team was created
updated_at:
type: string
description: When the team was last updated
description:
type: string
description: The description of the team
nullable: true
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
required:
- id
- display_name
- creator
- members
- databases
- analyst_databases
- name
- slug
- created_at
- updated_at
- description
- managed
required:
- type
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
OrganizationTeam:
type: object
properties:
id:
type: string
description: The ID of the team
display_name:
type: string
description: The display name of the team
creator:
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
members:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: >-
Whether or not the user has configured two factor
authentication
default_organization:
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
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: >-
Whether or not the user is managed by an authentication
provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
analyst_databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
name:
type: string
description: The name of the team
slug:
type: string
description: The slug of the team
created_at:
type: string
description: When the team was created
updated_at:
type: string
description: When the team was last updated
description:
type: string
description: The description of the team
nullable: true
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
required:
- id
- display_name
- creator
- members
- databases
- analyst_databases
- name
- slug
- created_at
- updated_at
- description
- managed