openapi: 3.0.1
info:
title: PlanetScale API
description: |-
PlanetScale API
© 2025 PlanetScale, Inc.
version: v1
x-copyright: "© 2025 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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Gets the organizations for the current user
headers: {}
content:
application/json:
schema: &a32
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
database_count:
type: number
description: The number of databases in the organization
sso_portal_url:
type: string
description: The URL of the organization's SSO portal
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: number
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: number
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
additionalProperties: false
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- has_past_due_invoices
- database_count
- sso_portal_url
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
additionalProperties: false
required:
- 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/{name}:
get:
tags:
- Organizations
operationId: get_organization
summary: Get an organization
parameters:
- name: name
in: path
required: true
description: The name of the organization
schema:
type: string
responses:
"200":
description: Returns an organization
headers: {}
content:
application/json:
schema: &a1
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
database_count:
type: number
description: The number of databases in the organization
sso_portal_url:
type: string
description: The URL of the organization's SSO portal
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: number
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: number
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
additionalProperties: false
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- has_past_due_invoices
- database_count
- sso_portal_url
- 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: name
in: path
required: true
description: The name of the organization
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: number
description: The expected monthly budget for the organization
additionalProperties: false
responses:
"200":
description: Returns the updated organization
headers: {}
content:
application/json:
schema: *a1
"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/{name}/audit-log:
get:
tags:
- Organizations
operationId: list_audit_logs
summary: List audit logs
parameters:
- name: name
in: path
required: true
description: The name of the organization
schema:
type: string
responses:
"200":
description: Returns the audit log events
headers: {}
content:
application/json:
schema: &a33
type: object
properties:
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
cursor_end:
type: string
description: The ID of the last object in the current results
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
actor_type:
type: string
description: The type of the actor. Such as 'User' or 'ServiceToken'
auditable_id:
type: string
description: The ID of the auditable object
auditable_type:
type: string
description: The type of the auditable. Such as 'Organization' or 'Database'
target_id:
type: string
description: The ID of the target
target_type:
type: string
description: The type of the target. Such as 'DatabaseBranch' or 'DatabaseBranchPassword'
location:
type: string
description: The location of the actor based on their IP address
target_display_name:
type: string
description: The name of the target
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
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
additionalProperties: false
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
additionalProperties: false
required:
- 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/{name}/regions:
get:
tags:
- Organizations
operationId: list_regions_for_organization
summary: List regions for an organization
parameters:
- name: name
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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns the organization's regions
headers: {}
content:
application/json:
schema: &a15
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
additionalProperties: false
required:
- 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}/databases:
get:
tags:
- Databases
operationId: list_databases
summary: List databases
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Retrieves the databases for an organization
headers: {}
content:
application/json:
schema: &a26
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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: number
description: The total number of database branches
open_schema_recommendations_count:
type: number
description: The total number of schema recommendations
development_branches_count:
type: number
description: The total number of database development branches
production_branches_count:
type: number
description: The total number of database production branches
issues_count:
type: number
description: The total number of ongoing issues within a database
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
finished_at:
type: string
description: When the import finished
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: number
description: Port of the data source
database:
type: string
description: Database name of the data source
additionalProperties: false
required:
- hostname
- port
- database
additionalProperties: false
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
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: number
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: number
description: Number of read only regions in the default branch
default_branch_table_count:
type: number
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
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
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
migration_framework:
type: string
description: Framework used for applying migrations
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.
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
additionalProperties: false
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- issues_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- data_import
- 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
- allow_data_branching
- foreign_keys_enabled
- automatic_migrations
- restrict_branch_region
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- migration_table_name
- migration_framework
- created_at
- updated_at
- schema_last_updated_at
- kind
additionalProperties: false
required:
- 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`, `delete_branch_password`, `delete_production_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_schema_recommendations`, `close_schema_recommendations`, `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: The name of the organization the database belongs to
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. Options: PS_10, PS_20, PS_40, PS_80, PS_160, PS_320, PS_400, PS_640, PS_700, PS_900, PS_1280, PS_1400, PS_1800, PS_2100, PS_2560, PS_2700, PS_2800."
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database to create.
additionalProperties: false
required:
- name
- cluster_size
responses:
"201":
description: Returns the created database
headers: {}
content:
application/json:
schema: &a14
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: number
description: The total number of database branches
open_schema_recommendations_count:
type: number
description: The total number of schema recommendations
development_branches_count:
type: number
description: The total number of database development branches
production_branches_count:
type: number
description: The total number of database production branches
issues_count:
type: number
description: The total number of ongoing issues within a database
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
finished_at:
type: string
description: When the import finished
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: number
description: Port of the data source
database:
type: string
description: Database name of the data source
additionalProperties: false
required:
- hostname
- port
- database
additionalProperties: false
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
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: number
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: number
description: Number of read only regions in the default branch
default_branch_table_count:
type: number
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
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
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
migration_framework:
type: string
description: Framework used for applying migrations
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.
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
additionalProperties: false
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- issues_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- data_import
- 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
- allow_data_branching
- foreign_keys_enabled
- automatic_migrations
- restrict_branch_region
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- migration_table_name
- migration_framework
- 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}/branches:
get:
tags:
- Database branches
operationId: list_branches
summary: List branches
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: 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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns database branches
headers: {}
content:
application/json:
schema: &a20
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_count:
type: number
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: number
description: IOPS for the cluster
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: number
description: The number of shards in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_count
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- sharded
- shard_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
additionalProperties: false
required:
- 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
parent_branch:
type: string
description: Parent branch
backup_id:
type: string
description: If provided, restores the backup's schema and data to the new branch. Must have `restore_production_branch_backup(s)` or `restore_backup(s)` access to do this.
region:
type: string
description: The region to create the branch in. If not provided, the branch will be created in the default region for its database.
restore_point:
type: string
description: Restore from a point-in-time recovery timestamp (e.g. 2023-01-01T00:00:00Z). Available only for PostgreSQL databases.
seed_data:
type: string
enum:
- last_successful_backup
description: If provided, restores the last successful backup's schema and data to the new branch. Must have `restore_production_branch_backup(s)` or `restore_backup(s)` access to do this, in addition to Data Branching™ being enabled for the branch.
cluster_size:
type: string
description: "The database cluster size is required if a backup_id is provided. Options: PS_10, PS_20, PS_40, ..., PS_2800"
additionalProperties: false
required:
- name
- parent_branch
responses:
"201":
description: Returns the created branch
headers: {}
content:
application/json:
schema: &a9
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_count:
type: number
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: number
description: IOPS for the cluster
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: number
description: The number of shards in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_count
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- sharded
- shard_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
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}/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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns database branch backups
headers: {}
content:
application/json:
schema: &a17
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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: number
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
expires_at:
type: string
description: When the backup expires
completed_at:
type: string
description: When the backup completed
deleted_at:
type: string
description: When the backup was deleted
pvc_size:
type: number
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
additionalProperties: false
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
backup_policy:
type: object
properties:
id:
type: string
description: The ID 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: number
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: number
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: string
enum:
- 0
- 1
- 2
- 3
- 4
- 5
- 6
description: Day of the week that the backup is scheduled
schedule_week:
type: string
enum:
- 0
- 1
- 2
- 3
description: Week of the month that the backup is scheduled
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
next_run_at:
type: string
description: When the backup will next run
required:
type: boolean
description: Whether the policy is a required system backup
additionalProperties: false
required:
- id
- 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
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
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
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
- backup_policy
- schema_snapshot
- database_branch
additionalProperties: false
required:
- 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: number
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.
additionalProperties: false
responses:
"201":
description: Returns the created database branch backup
headers: {}
content:
application/json:
schema: &a2
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: number
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
expires_at:
type: string
description: When the backup expires
completed_at:
type: string
description: When the backup completed
deleted_at:
type: string
description: When the backup was deleted
pvc_size:
type: number
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
additionalProperties: false
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
backup_policy:
type: object
properties:
id:
type: string
description: The ID 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: number
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: number
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: string
enum:
- 0
- 1
- 2
- 3
- 4
- 5
- 6
description: Day of the week that the backup is scheduled
schedule_week:
type: string
enum:
- 0
- 1
- 2
- 3
description: Week of the month that the backup is scheduled
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
next_run_at:
type: string
description: When the backup will next run
required:
type: boolean
description: Whether the policy is a required system backup
additionalProperties: false
required:
- id
- 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
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
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
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
- backup_policy
- schema_snapshot
- 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**
`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: *a2
"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
additionalProperties: false
responses:
"200":
description: Returns the backup
headers: {}
content:
application/json:
schema: *a2
"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: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns bouncer resize requests
headers: {}
content:
application/json:
schema: &a4
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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: number
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: number
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
completed_at:
type: string
description: The time the bouncer resize completed
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
additionalProperties: false
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
additionalProperties: false
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: number
description: The amount of memory in bytes
sort_order:
type: number
description: The sort order of the Postgres bouncer SKU
additionalProperties: false
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: number
description: The amount of memory in bytes
sort_order:
type: number
description: The sort order of the Postgres bouncer SKU
additionalProperties: false
required:
- name
- display_name
- cpu
- ram
- sort_order
additionalProperties: false
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
additionalProperties: false
required:
- 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: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns bouncers
headers: {}
content:
application/json:
schema: &a35
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
target:
type: string
enum:
- primary
- replica
description: The instance type the bouncer targets
replicas_per_cell:
type: number
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
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
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
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- internal
- milliseconds
- 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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- namespace
- name
- display_name
- category
- description
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
additionalProperties: false
required:
- id
- name
- target
- replicas_per_cell
- created_at
- updated_at
- deleted_at
- actor
- branch
- parameters
additionalProperties: false
required:
- 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: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
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: number
description: The number of replica servers per cell
additionalProperties: false
responses:
"200":
description: Returns the new bouncer
headers: {}
content:
application/json:
schema: &a3
type: object
properties:
id:
type: string
description: The ID of the bouncer
name:
type: string
description: The name of the bouncer
target:
type: string
enum:
- primary
- replica
description: The instance type the bouncer targets
replicas_per_cell:
type: number
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
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
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
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- internal
- milliseconds
- 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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- namespace
- name
- display_name
- category
- description
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
additionalProperties: false
required:
- id
- name
- 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/{name}:
get:
tags:
- Bouncers
operationId: get_bouncer
summary: Get a bouncer
parameters:
- name: organization
in: path
required: true
description: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
schema:
type: string
- name: name
in: path
required: true
description: The name of the bouncer
schema:
type: string
responses:
"200":
description: Returns a bouncer
headers: {}
content:
application/json:
schema: *a3
"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: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
schema:
type: string
- name: name
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/{name}/resizes:
get:
tags:
- Bouncer resizes
operationId: list_bouncer_resize_requests
summary: Get bouncer resize requests
parameters:
- name: organization
in: path
required: true
description: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
schema:
type: string
- name: name
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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns bouncer resize requests
headers: {}
content:
application/json:
schema: *a4
"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: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
schema:
type: string
- name: name
in: path
required: true
description: The name of the bouncer
schema:
type: string
responses:
"200":
description: Returns bouncer resize request
headers: {}
content:
application/json:
schema: &a34
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: number
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: number
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
completed_at:
type: string
description: The time the bouncer resize completed
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
additionalProperties: false
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
additionalProperties: false
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: number
description: The amount of memory in bytes
sort_order:
type: number
description: The sort order of the Postgres bouncer SKU
additionalProperties: false
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: number
description: The amount of memory in bytes
sort_order:
type: number
description: The sort order of the Postgres bouncer SKU
additionalProperties: false
required:
- name
- display_name
- cpu
- ram
- sort_order
additionalProperties: false
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: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
schema:
type: string
- name: name
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: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns branch change requests
headers: {}
content:
application/json:
schema: &a18
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the branch change request
restart:
items:
type: number
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
completed_at:
type: string
description: The time the branch change request completed
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
additionalProperties: false
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: number
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: number
description: The previous total number of replicas
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: number
description: The minimum storage size in bytes
maximum_storage_bytes:
type: number
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: number
description: The storage IOPS
storage_throughput_mibs:
type: number
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: number
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: number
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: number
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: number
description: The previous storage throughput in MiB/s
additionalProperties: false
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
additionalProperties: false
required:
- 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: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
schema:
type: string
responses:
"200":
description: Returns the branch change request
headers: {}
content:
application/json:
schema: &a19
type: object
properties:
id:
type: string
description: The ID of the branch change request
restart:
items:
type: number
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
completed_at:
type: string
description: The time the branch change request completed
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
additionalProperties: false
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: number
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: number
description: The previous total number of replicas
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: number
description: The minimum storage size in bytes
maximum_storage_bytes:
type: number
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: number
description: The storage IOPS
storage_throughput_mibs:
type: number
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: number
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: number
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: number
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: number
description: The previous storage throughput in MiB/s
additionalProperties: false
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**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/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: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
schema:
type: string
responses:
"200":
description: Returns cluster extensions
headers: {}
content:
application/json:
schema:
type: array
items: &a22
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
url:
type: string
description: The URL of the extension
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
internal:
type: boolean
description: The internal state of the parameter
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- internal
- milliseconds
- 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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- name
- display_name
- namespace
- category
- description
- extension
- internal
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
additionalProperties: false
required:
- id
- name
- description
- internal
- url
- 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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns keyspaces
headers: {}
content:
application/json:
schema: &a24
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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: number
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: number
description: Total number of replicas in the keyspace
extra_replicas:
type: number
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
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
replication_durability_constraints:
type: object
properties:
strategy:
type: string
enum:
- available
- lag
- always
description: The replication durability strategy
additionalProperties: false
required:
- strategy
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
additionalProperties: false
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
additionalProperties: false
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_pending
- ready
- metal
- default
- imported
- vector_pool_allocation
- replication_durability_constraints
- vreplication_flags
additionalProperties: false
required:
- 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:
- 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
additionalProperties: false
required:
- name
responses:
"200":
description: Returns a created keyspace
headers: {}
content:
application/json:
schema: &a5
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: number
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: number
description: Total number of replicas in the keyspace
extra_replicas:
type: number
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
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
replication_durability_constraints:
type: object
properties:
strategy:
type: string
enum:
- available
- lag
- always
description: The replication durability strategy
additionalProperties: false
required:
- strategy
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
additionalProperties: false
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
additionalProperties: false
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_pending
- ready
- metal
- default
- imported
- vector_pool_allocation
- replication_durability_constraints
- vreplication_flags
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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}/keyspaces/{name}:
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: name
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: *a5
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
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: name
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
"200":
description: Returns the keyspace
headers: {}
content:
application/json:
schema: *a5
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
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: name
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: |+
/organizations/{organization}/databases/{database}/branches/{branch}/keyspaces/{name}/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: name
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
additionalProperties: false
required:
- name
- last_rollout_started_at
- last_rollout_finished_at
- state
additionalProperties: false
required:
- name
- state
- shards
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/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: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
schema:
type: string
responses:
"200":
description: Returns cluster parameters
headers: {}
content:
application/json:
schema:
type: array
items: &a23
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
internal:
type: boolean
description: The internal state of the parameter
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- internal
- milliseconds
- 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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- name
- display_name
- namespace
- category
- description
- extension
- internal
- 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: |-
### 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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns passwords for the branch
headers: {}
content:
application/json:
schema: &a25
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
expires_at:
type: string
description: When the password will expire
last_used_at:
type: string
description: When the password was last used to execute a query
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
ttl_seconds:
type: number
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
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
additionalProperties: false
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
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plain text password, available only after create
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
additionalProperties: false
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
additionalProperties: false
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
additionalProperties: false
required:
- 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 | `manage_passwords`, `manage_production_branch_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords` |
| Branch | `manage_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: number
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
additionalProperties: false
responses:
"201":
description: Returns the new credentials
headers: {}
content:
application/json:
schema: &a6
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
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
expires_at:
type: string
description: When the password will expire
last_used_at:
type: string
description: When the password was last used to execute a query
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
ttl_seconds:
type: number
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
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
additionalProperties: false
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
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plain text password, available only after create
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
additionalProperties: false
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
additionalProperties: false
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- 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_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords` |
| Branch | `manage_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: *a6
"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 | `manage_passwords`, `manage_production_branch_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords` |
| Branch | `manage_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
additionalProperties: false
responses:
"200":
description: Returns the updated password
headers: {}
content:
application/json:
schema: *a6
"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_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords` |
| Branch | `manage_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_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords` |
| Branch | `manage_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: *a6
"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_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords` |
| Branch | `manage_passwords` |
/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
responses:
"200":
description: Returns the generated query patterns reports
headers: {}
content:
application/json:
schema: &a37
type: object
properties:
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
cursor_end:
type: string
description: The ID of the last object in the current results
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
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- state
- created_at
- finished_at
- url
- download_url
- actor
additionalProperties: false
required:
- 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: &a7
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
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
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: *a7
"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: *a7
"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: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
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: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns roles
headers: {}
content:
application/json:
schema: &a36
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
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
expires_at:
type: string
description: When the role expires
dropped_at:
type: string
description: When the role was dropped
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: number
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- 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
additionalProperties: false
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
additionalProperties: false
required:
- 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 | `manage_passwords`, `manage_production_branch_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords` |
| Branch | `manage_passwords` |
post:
tags:
- Roles
operationId: create_role
summary: Create role credentials
parameters:
- name: organization
in: path
required: true
description: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
ttl:
type: number
description: Time to live in seconds
inherited_roles:
type: array
items:
type: string
enum:
- 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
additionalProperties: false
responses:
"200":
description: Returns the new credentials
headers: {}
content:
application/json:
schema: &a8
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
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
expires_at:
type: string
description: When the role expires
dropped_at:
type: string
description: When the role was dropped
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: number
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- 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
additionalProperties: false
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- 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**
`create_production_branch_password`, `create_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords` |
| Branch | `manage_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: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
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: *a8
"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 | `manage_passwords`, `manage_production_branch_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords` |
| Branch | `manage_passwords` |
patch:
tags:
- Roles
operationId: update_role
summary: Update role name
parameters:
- name: organization
in: path
required: true
description: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
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
additionalProperties: false
responses:
"200":
description: Returns the updated role
headers: {}
content:
application/json:
schema: *a8
"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_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords` |
| Branch | `manage_passwords` |
delete:
tags:
- Roles
operationId: delete_role
summary: Delete role credentials
parameters:
- name: organization
in: path
required: true
description: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
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 optional role to reassign ownership to before dropping
additionalProperties: false
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_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords` |
| Branch | `manage_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: The name of the organization that owns this resource
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that owns this resource
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch that owns this resource
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: *a8
"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_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords` |
| Branch | `manage_passwords` |
/organizations/{organization}/databases/{database}/branches/{name}:
get:
tags:
- Database branches
operationId: get_branch
summary: Get 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: name
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
"200":
description: Returns information about a branch
headers: {}
content:
application/json:
schema: *a9
"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:
- 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: name
in: path
required: true
description: The name of the branch
schema:
type: string
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/{name}/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: name
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,…"
additionalProperties: false
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/{name}/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: name
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: *a9
"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/{name}/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: name
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: *a9
"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/{name}/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: name
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: *a9
"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: name
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: *a9
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/branches/{name}/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: name
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
additionalProperties: false
required:
- name
- html
- raw
additionalProperties: false
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/{name}/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: name
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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns a list of schema errors for a branch
headers: {}
content:
application/json:
schema: &a21
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
additionalProperties: false
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
additionalProperties: false
required:
- 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}/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
responses:
"200":
description: Returns the deploy queue for a database
headers: {}
content:
application/json:
schema: &a46
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
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
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
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
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: number
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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
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
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
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
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: number
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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: number
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: number
description: The estimated seconds until completion for the deploy operation
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
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:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
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
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- 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
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
additionalProperties: false
required:
- 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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns a list of deploy requests
headers: {}
content:
application/json:
schema: &a43
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: number
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
additionalProperties: false
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
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: number
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
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
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
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
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: number
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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
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
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
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
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: number
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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: number
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: number
description: The estimated seconds until completion for the deploy operation
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
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:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
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
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- 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
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: number
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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- 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
additionalProperties: false
required:
- 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.
additionalProperties: false
required:
- branch
- into_branch
responses:
"201":
description: Returns the created deploy request
headers: {}
content:
application/json:
schema: &a10
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: number
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
additionalProperties: false
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
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: number
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
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
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
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
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: number
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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
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
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
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
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: number
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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: number
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: number
description: The estimated seconds until completion for the deploy operation
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
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:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
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
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- 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
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: number
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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- 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: string
responses:
"200":
description: Returns information about a deploy request
headers: {}
content:
application/json:
schema: *a10
"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: string
requestBody:
content:
application/json:
schema:
type: object
properties:
state:
type: string
enum:
- closed
description: The deploy request will be updated to this state
additionalProperties: false
responses:
"200":
description: Returns the updated deploy request
headers: {}
content:
application/json:
schema: *a10
"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: string
responses:
"200":
description: Returns the deploy request whose deployment has been completed
headers: {}
content:
application/json:
schema: *a10
"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: string
requestBody:
content:
application/json:
schema:
type: object
properties:
enable:
type: boolean
description: Whether or not to enable auto-apply for the deploy request
additionalProperties: false
responses:
"200":
description: Returns the deploy request whose auto-apply setting was updated
headers: {}
content:
application/json:
schema: *a10
"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}/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: string
responses:
"200":
description: Returns the deploy request whose deployment was canceled
headers: {}
content:
application/json:
schema: *a10
"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: string
responses:
"200":
description: Returns the completed deploy request
headers: {}
content:
application/json:
schema: *a10
"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: string
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.
additionalProperties: false
responses:
"200":
description: Returns the deployed deploy request
headers: {}
content:
application/json:
schema: *a10
"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: string
responses:
"200":
description: Returns the deployment for a deploy request
headers: {}
content:
application/json:
schema: &a44
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
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
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
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
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: number
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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
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
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
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
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: number
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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: number
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: number
description: The estimated seconds until completion for the deploy operation
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
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:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
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
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- 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
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
"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: string
- 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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns deploy operations for the deploy request
headers: {}
content:
application/json:
schema: &a45
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
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
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
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
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
additionalProperties: false
required:
- 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: string
responses:
"200":
description: Returns the deploy request that was reverted
headers: {}
content:
application/json:
schema: *a10
"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: string
responses:
"200":
description: Returns an array of deploy request reviews
headers: {}
content:
application/json:
schema: &a41
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- body
- html_body
- state
- created_at
- updated_at
- actor
additionalProperties: false
required:
- 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: string
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
additionalProperties: false
responses:
"201":
description: Returns the created deploy request review
headers: {}
content:
application/json:
schema: &a42
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
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: string
responses:
"200":
description: Returns the deploy request whose deploy revert was skipped
headers: {}
content:
application/json:
schema: *a10
"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}/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: string
responses:
"200":
description: Deploy request throttler configurations
headers: {}
content:
application/json:
schema: &a11
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
additionalProperties: false
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
additionalProperties: false
required:
- keyspace_name
- ratio
additionalProperties: false
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: string
requestBody:
content:
application/json:
schema:
type: object
properties:
ratio:
type: number
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'
additionalProperties: false
responses:
"200":
description: Deploy request throttler configurations
headers: {}
content:
application/json:
schema: *a11
"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}/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: *a11
"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: number
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'
additionalProperties: false
responses:
"200":
description: Database throttler configurations
headers: {}
content:
application/json:
schema: *a11
"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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns a list of webhooks for a database
headers: {}
content:
application/json:
schema: &a47
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
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.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
additionalProperties: false
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
additionalProperties: false
required:
- 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
additionalProperties: false
required:
- url
responses:
"201":
description: Returns the created webhook
headers: {}
content:
application/json:
schema: &a12
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
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.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
additionalProperties: false
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: *a12
"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
additionalProperties: false
responses:
"200":
description: Returns the updated webhook
headers: {}
content:
application/json:
schema: *a12
"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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns workflows
headers: {}
content:
application/json:
schema: &a40
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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: number
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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
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
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
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
additionalProperties: false
required:
- 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
additionalProperties: false
required:
- name
- source_keyspace
- target_keyspace
- tables
responses:
"201":
description: Returns the workflow
headers: {}
content:
application/json:
schema: &a13
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: number
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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
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
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
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: string
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema: *a13
"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: string
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema: *a13
"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: string
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema: *a13
"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: string
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema: *a13
"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: string
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema: *a13
"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: string
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema: *a13
"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: string
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema: *a13
"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: string
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema: *a13
"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: string
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema: *a13
"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: string
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema: *a13
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{name}:
get:
tags:
- Databases
operationId: get_database
summary: Get a database
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: name
in: path
required: true
description: The name of the database
schema:
type: string
responses:
"200":
description: Returns a database
headers: {}
content:
application/json:
schema: *a14
"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`, `delete_branch_password`, `delete_production_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_schema_recommendations`, `close_schema_recommendations`, `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: The name of the organization the database belongs to
schema:
type: string
- name: name
in: path
required: true
description: The name of the database
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
additionalProperties: false
responses:
"200":
description: Returns the updated database
headers: {}
content:
application/json:
schema: *a14
"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: The name of the organization the database belongs to
schema:
type: string
- name: name
in: path
required: true
description: The name of the database
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/{name}/read-only-regions:
get:
tags:
- Databases
operationId: list_read_only_regions
summary: List read-only regions
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: name
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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: List of the database's read-only regions
headers: {}
content:
application/json:
schema: &a27
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
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
additionalProperties: false
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
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
additionalProperties: false
required:
- id
- display_name
- created_at
- updated_at
- ready_at
- ready
- actor
- region
additionalProperties: false
required:
- 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`, `delete_branch_password`, `delete_production_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_schema_recommendations`, `close_schema_recommendations`, `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/{name}/regions:
get:
tags:
- Databases
operationId: list_database_regions
summary: List database regions
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: name
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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns the available regions for a database
headers: {}
content:
application/json:
schema: *a15
"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`, `delete_branch_password`, `delete_production_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_schema_recommendations`, `close_schema_recommendations`, `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}/invoices:
get:
tags:
- Invoices
operationId: list_invoices
summary: Get invoices
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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Gets the invoices for an organization
headers: {}
content:
application/json:
schema: &a49
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the invoice
total:
type: number
description: The total amount of the invoice
billing_period_start:
type: string
description: Start of the billing period
billing_period_end:
type: string
description: End of the billing period
additionalProperties: false
required:
- id
- total
- billing_period_start
- billing_period_end
additionalProperties: false
required:
- 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: The name of the organization
schema:
type: string
- name: id
in: path
required: true
description: The ID of the invoice
schema:
type: string
responses:
"200":
description: Returns an invoice
headers: {}
content:
application/json:
schema: &a50
type: object
properties:
id:
type: string
description: The ID of the invoice
total:
type: number
description: The total amount of the invoice
billing_period_start:
type: string
description: Start of the billing period
billing_period_end:
type: string
description: End of the billing period
additionalProperties: false
required:
- id
- total
- billing_period_start
- billing_period_end
"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: The name of the organization
schema:
type: string
- name: id
in: path
required: true
description: The ID of the invoice
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Gets the line items for an invoice
headers: {}
content:
application/json:
schema: &a48
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- subtotal
- description
- metric_name
- database_id
- database_name
- resource
additionalProperties: false
required:
- 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: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns members of the organization
headers: {}
content:
application/json:
schema: &a31
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
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
additionalProperties: false
required:
- id
- user
- role
- created_at
- updated_at
additionalProperties: false
required:
- 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_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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns a list of the organization's oauth applications
headers: {}
content:
application/json:
schema: &a28
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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:
items:
type: string
type: array
description: The scopes that the OAuth application requires on a user account
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: number
description: The number of tokens issued by the OAuth application
additionalProperties: false
required:
- id
- name
- redirect_uri
- domain
- created_at
- updated_at
- scopes
- avatar
- client_id
- tokens
additionalProperties: false
required:
- 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: &a29
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:
items:
type: string
type: array
description: The scopes that the OAuth application requires on a user account
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: number
description: The number of tokens issued by the OAuth application
additionalProperties: false
required:
- id
- name
- redirect_uri
- domain
- created_at
- updated_at
- scopes
- avatar
- client_id
- tokens
"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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns the OAuth tokens issued on behalf of the OAuth application
headers: {}
content:
application/json:
schema: &a30
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plain text token. Available only after create.
plain_text_refresh_token:
type: string
description: The plain text refresh token. Available only after create.
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
last_used_at:
type: string
description: When the service token was last used
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
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
additionalProperties: false
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
additionalProperties: false
required:
- name
- description
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
required:
- name
- description
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
required:
- name
- description
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- users
- accesses
additionalProperties: false
required:
- database
- organization
- branch
- user
additionalProperties: false
required:
- id
- name
- display_name
- token
- plain_text_refresh_token
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
- service_token_accesses
- oauth_accesses_by_resource
additionalProperties: false
required:
- 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: &a16
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plain text token. Available only after create.
plain_text_refresh_token:
type: string
description: The plain text refresh token. Available only after create.
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
last_used_at:
type: string
description: When the service token was last used
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
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
additionalProperties: false
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
additionalProperties: false
required:
- name
- description
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
required:
- name
- description
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
required:
- name
- description
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- users
- accesses
additionalProperties: false
required:
- database
- organization
- branch
- user
additionalProperties: false
required:
- id
- name
- display_name
- token
- plain_text_refresh_token
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
- service_token_accesses
- oauth_accesses_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_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
additionalProperties: false
required:
- client_id
- client_secret
- grant_type
responses:
"200":
description: Returns the created OAuth token
headers: {}
content:
application/json:
schema: *a16
"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`
/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: number
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: number
default: 25
responses:
"200":
description: Returns the available public PlanetScale regions
headers: {}
content:
application/json:
schema: &a38
type: object
properties:
current_page:
type: number
description: The current page number
next_page:
type: number
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: number
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
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
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
additionalProperties: false
required:
- 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: &a39
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
"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: Backups
description: |2
Resources for managing database branch backups.
- name: Branch changes
description: |2
Resources for managing cluster changes.
- name: Cluster extensions
description: |2
Resources for managing cluster extension configuration.
- name: 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 CIDRs
description: |2
Resources for managing Postgres IP allowlist entries for databases.
- name: Databases
description: |2
Resources for managing databases within an organization.
- name: Keyspace VSchemas
description: |2
Resources for managing VSchemas within a keyspace.
- name: OAuth applications
description: |2
Resources for managing OAuth applications.
- name: OAuth tokens
description: |2
Resources for managing OAuth tokens.
- name: 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: 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.
security:
- ApiKeyHeader:
- Authorization
x-readme:
explorer-enabled: false
servers:
- url: https://api.planetscale.com/v1
components:
securitySchemes:
ApiKeyHeader:
type: apiKey
in: header
name: Authorization
schemas:
PaginatedBackup: *a17
Backup: *a2
PaginatedPostgresBouncerResizeRequest: *a4
PaginatedPostgresClusterResizeRequest: *a18
PostgresClusterResizeRequest: *a19
PaginatedDatabaseBranch: *a20
DatabaseBranch: *a9
PaginatedSchemaLintError: *a21
PostgresClusterExtension: *a22
PostgresClusterParameter: *a23
PaginatedDatabaseBranchKeyspace: *a24
DatabaseBranchKeyspace: *a5
PaginatedDatabaseBranchPassword: *a25
DatabaseBranchPassword: *a6
PaginatedDatabase: *a26
Database: *a14
PaginatedPlanetscaleRegion: *a15
PaginatedDatabaseBranchReadOnlyRegion: *a27
ThrottlerConfigurations: *a11
PaginatedOauthApplication: *a28
OauthApplication: *a29
PaginatedServiceToken: *a30
ServiceToken: *a16
PaginatedOrganizationMembership: *a31
PaginatedOrganization: *a32
Organization: *a1
PaginatedAuditLogEvent: *a33
PostgresBouncerResizeRequest: *a34
PaginatedPostgresBouncer: *a35
PostgresBouncer: *a3
PaginatedPostgresRole: *a36
PostgresRole: *a8
PaginatedQueryPatternsDownload: *a37
QueryPatternsDownload: *a7
PaginatedPublicPlanetscaleRegionSerializer: *a38
User: *a39
PaginatedWorkflow: *a40
Workflow: *a13
PaginatedDeployRequestReview: *a41
DeployRequestReview: *a42
PaginatedDatabaseDeployRequest: *a43
DatabaseDeployRequest: *a10
Deployment: *a44
PaginatedDeployOperation: *a45
PaginatedDeployment: *a46
PaginatedDatabaseWebhook: *a47
DatabaseWebhook: *a12
PaginatedLineItem: *a48
PaginatedInvoice: *a49
Invoice: *a50