openapi: 3.0.1
info:
title: PlanetScale API
description: |-
PlanetScale API
© 2026 PlanetScale, Inc.
version: v1
x-copyright: "© 2026 PlanetScale, Inc."
paths:
/organizations:
get:
tags:
- Organizations
operationId: list_organizations
summary: List organizations
parameters:
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Gets the organizations for the current user
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the organization
name:
type: string
description: The name of the organization
billing_email:
type: string
description: The billing email of the organization
created_at:
type: string
description: When the organization was created
updated_at:
type: string
description: When the organization was last updated
plan:
type: string
description: The billing plan of the organization
valid_billing_info:
type: boolean
description: Whether or not the organization's billing information is valid
sso:
type: boolean
description: Whether or not SSO is enabled on the organization
sso_directory:
type: boolean
description: Whether or not the organization uses an SSO directory
single_tenancy:
type: boolean
description: Whether or not the organization has single tenancy enabled
managed_tenancy:
type: boolean
description: Whether or not the organization has managed tenancy enabled
has_past_due_invoices:
type: boolean
description: Whether or not the organization has past due billing invoices.
nullable: true
database_count:
type: integer
description: The number of databases in the organization
sso_portal_url:
type: string
description: The URL of the organization's SSO portal.
nullable: true
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: Whether or not the IdP provider is be responsible for managing roles in PlanetScale
invoice_budget_amount:
type: string
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: integer
description: The keyspace shard limit for the organization
has_card:
type: boolean
description: Whether or not the organization has a payment method on file
payment_info_required:
type: boolean
description: Whether or not the organization requires payment information
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- database_count
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
When using a service token, returns the list of organizations the service token has access to. When using an OAuth token, returns the list of organizations the user has access to.
### Authorization
A OAuth token must have at least one of the following scopes in order to use this API endpoint:
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| User | `read_organizations` |
/organizations/{organization}:
get:
tags:
- Organizations
operationId: get_organization
summary: Get an organization
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
responses:
"200":
description: Returns an organization
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID for the organization
name:
type: string
description: The name of the organization
billing_email:
type: string
description: The billing email of the organization
created_at:
type: string
description: When the organization was created
updated_at:
type: string
description: When the organization was last updated
plan:
type: string
description: The billing plan of the organization
valid_billing_info:
type: boolean
description: Whether or not the organization's billing information is valid
sso:
type: boolean
description: Whether or not SSO is enabled on the organization
sso_directory:
type: boolean
description: Whether or not the organization uses an SSO directory
single_tenancy:
type: boolean
description: Whether or not the organization has single tenancy enabled
managed_tenancy:
type: boolean
description: Whether or not the organization has managed tenancy enabled
has_past_due_invoices:
type: boolean
description: Whether or not the organization has past due billing invoices.
nullable: true
database_count:
type: integer
description: The number of databases in the organization
sso_portal_url:
type: string
description: The URL of the organization's SSO portal.
nullable: true
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: Whether or not the IdP provider is be responsible for managing roles in PlanetScale
invoice_budget_amount:
type: string
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: integer
description: The keyspace shard limit for the organization
has_card:
type: boolean
description: Whether or not the organization has a payment method on file
payment_info_required:
type: boolean
description: Whether or not the organization requires payment information
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- database_count
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| User | `read_organizations` |
| Organization | `read_organization` |
patch:
tags:
- Organizations
operationId: update_organization
summary: Update an organization
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
billing_email:
type: string
description: The billing email for the organization
idp_managed_roles:
type: boolean
description: Whether or not the IdP provider is be responsible for managing roles in PlanetScale
invoice_budget_amount:
type: integer
description: The expected monthly budget for the organization
responses:
"200":
description: Returns the updated organization
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID for the organization
name:
type: string
description: The name of the organization
billing_email:
type: string
description: The billing email of the organization
created_at:
type: string
description: When the organization was created
updated_at:
type: string
description: When the organization was last updated
plan:
type: string
description: The billing plan of the organization
valid_billing_info:
type: boolean
description: Whether or not the organization's billing information is valid
sso:
type: boolean
description: Whether or not SSO is enabled on the organization
sso_directory:
type: boolean
description: Whether or not the organization uses an SSO directory
single_tenancy:
type: boolean
description: Whether or not the organization has single tenancy enabled
managed_tenancy:
type: boolean
description: Whether or not the organization has managed tenancy enabled
has_past_due_invoices:
type: boolean
description: Whether or not the organization has past due billing invoices.
nullable: true
database_count:
type: integer
description: The number of databases in the organization
sso_portal_url:
type: string
description: The URL of the organization's SSO portal.
nullable: true
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: Whether or not the IdP provider is be responsible for managing roles in PlanetScale
invoice_budget_amount:
type: string
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: integer
description: The keyspace shard limit for the organization
has_card:
type: boolean
description: Whether or not the organization has a payment method on file
payment_info_required:
type: boolean
description: Whether or not the organization requires payment information
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- database_count
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A OAuth token must have at least one of the following scopes in order to use this API endpoint:
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
/organizations/{organization}/audit-log:
get:
tags:
- Organizations
operationId: list_audit_logs
summary: List audit logs
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: starting_after
in: query
description: If provided, returns results after the specified cursor
schema:
type: string
- name: ending_before
in: query
description: If provided, returns results before the specified cursor
schema:
type: string
- name: limit
in: query
description: If provided, specifies the number of returned results (max 100)
schema:
type: integer
default: 25
responses:
"200":
description: Returns the audit log events
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
has_next:
type: boolean
description: Whether there is a next page of results
has_prev:
type: boolean
description: Whether there is a previous page of results
cursor_start:
type: string
description: The ID of the first object in the current results, or null when there are no results
nullable: true
cursor_end:
type: string
description: The ID of the last object in the current results, or null when there are no results
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the audit log
actor_id:
type: string
description: The ID of the actor
nullable: true
actor_type:
type: string
description: The type of the actor. Such as 'User' or 'ServiceToken'
nullable: true
auditable_id:
type: string
description: The ID of the auditable object
nullable: true
auditable_type:
type: string
description: The type of the auditable. Such as 'Organization' or 'Database'
nullable: true
target_id:
type: string
description: The ID of the target
nullable: true
target_type:
type: string
description: The type of the target. Such as 'DatabaseBranch' or 'DatabaseBranchPassword'
nullable: true
location:
type: string
description: The location of the actor based on their IP address
nullable: true
target_display_name:
type: string
description: The name of the target
nullable: true
audit_action:
type: string
description: The action that was taken
action:
type: string
description: The action that was taken
actor_display_name:
type: string
description: The name of the actor
auditable_display_name:
type: string
description: The name of the auditable object
remote_ip:
type: string
description: The IP address of the actor
nullable: true
created_at:
type: string
description: When the audit log was created
updated_at:
type: string
description: When the audit log was last updated
metadata:
type: object
additionalProperties: true
description: Additional metadata containing details about the change
nullable: true
required:
- id
- actor_id
- actor_type
- auditable_id
- auditable_type
- target_id
- target_type
- location
- target_display_name
- audit_action
- action
- actor_display_name
- auditable_display_name
- remote_ip
- created_at
- updated_at
- metadata
required:
- type
- has_next
- has_prev
- cursor_start
- cursor_end
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token 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_audit_logs`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_audit_logs` |
/organizations/{organization}/billing/payment-method:
get:
tags:
- Billing payment method
operationId: get_organization_billing_payment_method
summary: Get the current billing payment method
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
responses:
"200":
description: Returns the organization's payment method
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- PaymentMethod
description: The resource type
id:
type: string
description: The payment method ID
brand:
type: string
description: The card brand, such as visa or mastercard
last4:
type: string
description: The final four digits of the card number
exp_month:
type: integer
description: The card expiration month
exp_year:
type: integer
description: The card expiration year
name:
type: string
description: The cardholder name
nullable: true
required:
- type
- id
- brand
- last4
- exp_month
- exp_year
- name
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Get the current payment method 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_payment_method`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_payment_method` |
delete:
tags:
- Billing payment method
operationId: delete_organization_billing_payment_method
summary: Delete the current billing payment method
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
responses:
"204":
description: The billing payment method was deleted
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Delete the current payment method 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**
`write_payment_method`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_payment_method` |
/organizations/{organization}/billing/payment-method-setups:
post:
tags:
- Billing payment method setup
operationId: update_payment_method
summary: Create a billing payment method setup
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
responses:
"201":
description: Returns the billing payment method setup
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- BillingPaymentMethodSetup
description: The resource type
id:
type: string
description: The billing payment method setup ID
state:
type: string
enum:
- pending
- completed
- failed
- expired
description: The setup state
checkout_url:
type: string
description: The hosted checkout URL while the setup is pending
nullable: true
error:
type: string
description: The failure message when the setup failed
nullable: true
expires_at:
type: string
description: When the pending setup expires
nullable: true
completed_at:
type: string
description: When the setup completed
nullable: true
failed_at:
type: string
description: When the setup failed
nullable: true
required:
- type
- id
- state
- checkout_url
- error
- expires_at
- completed_at
- failed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Create a hosted checkout session for adding or replacing an organization's payment method
### 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_payment_method`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_payment_method` |
/organizations/{organization}/billing/payment-method-setups/{id}:
get:
tags:
- Billing payment method setup
operationId: get_payment_method_setup
summary: Get a billing payment method setup
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: id
in: path
required: true
description: "Billing payment method setup ID from `update_payment_method`. Example: `pmsetup_1234`."
schema:
type: string
responses:
"200":
description: Returns the billing payment method setup
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- BillingPaymentMethodSetup
description: The resource type
id:
type: string
description: The billing payment method setup ID
state:
type: string
enum:
- pending
- completed
- failed
- expired
description: The setup state
checkout_url:
type: string
description: The hosted checkout URL while the setup is pending
nullable: true
error:
type: string
description: The failure message when the setup failed
nullable: true
expires_at:
type: string
description: When the pending setup expires
nullable: true
completed_at:
type: string
description: When the setup completed
nullable: true
failed_at:
type: string
description: When the setup failed
nullable: true
required:
- type
- id
- state
- checkout_url
- error
- expires_at
- completed_at
- failed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Get the state of a billing payment method setup
### 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_payment_method`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_payment_method` |
/organizations/{organization}/cluster-size-skus:
get:
tags:
- Organizations
operationId: list_cluster_size_skus
summary: List available cluster sizes
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: engine
in: query
description: The database engine to filter by. Defaults to 'mysql'.
schema:
type: string
enum:
- mysql
- postgresql
- name: rates
in: query
description: Whether to include pricing rates in the response. Defaults to false.
schema:
type: boolean
- name: region
in: query
description: The region slug to get rates for. If not specified, uses the organization's default region.
schema:
type: string
- name: database
in: query
description: The database name to resolve rates for. When specified, database-level custom rates take precedence over organization rates.
schema:
type: string
responses:
"200":
description: Returns available cluster sizes with optional pricing rates
headers: {}
content:
application/json:
schema:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the cluster SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The number of CPUs
storage:
type: integer
description: The amount of storage in bytes
nullable: true
ram:
type: integer
description: The amount of memory in bytes
metal:
type: boolean
description: Whether or not the cluster SKU is Metal
enabled:
type: boolean
description: Whether or not the cluster SKU is enabled for the organization
provider:
type: string
description: The provider of the cluster SKU (nil, AWS or GCP)
nullable: true
default_vtgate:
type: string
description: The default vtgate size for the cluster SKU
default_vtgate_rate:
type: number
description: The default vtgate rate for the cluster SKU
nullable: true
replica_rate:
type: number
description: The replica rate for the cluster SKU
nullable: true
rate:
type: number
description: The rate for the cluster SKU
nullable: true
sort_order:
type: integer
description: The sort order of the cluster SKU
architecture:
type: string
description: The architecture of the cluster SKU (null, x86_64 or arm64)
nullable: true
development:
type: boolean
description: Whether or not the cluster SKU is a development SKU
production:
type: boolean
description: Whether or not the cluster SKU is a production SKU
required:
- name
- display_name
- cpu
- storage
- ram
- metal
- enabled
- provider
- default_vtgate
- default_vtgate_rate
- sort_order
- development
- production
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
List available cluster sizes for an organization
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| User | `read_organizations` |
| Organization | `read_organization` |
/organizations/{organization}/databases:
get:
tags:
- Databases
operationId: list_databases
summary: List databases
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: q
in: query
description: Search term to filter databases by name
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Retrieves the databases for an organization
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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: integer
description: The total number of database branches
open_schema_recommendations_count:
type: integer
description: The total number of schema recommendations
development_branches_count:
type: integer
description: The total number of database development branches
production_branches_count:
type: integer
description: The total number of database production branches
issues_count:
type: integer
description: The total number of ongoing issues within a database
nullable: true
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: If the database has reached its backup restored branch limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
nullable: true
finished_at:
type: string
description: When the import finished
nullable: true
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
required:
- hostname
- port
- database
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: Whether an approval is required to deploy schema changes to this database
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
config_changing:
type: boolean
description: True if a config change is in progress
config_change_queued:
type: boolean
description: True if a config change is queued for maintenance window
allow_data_branching:
type: boolean
description: Whether seeding branches with data is enabled for all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: Whether to automatically manage Rails migrations during deploy requests.
nullable: true
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
prefer_instant:
type: boolean
description: Whether deploy requests default to instant deploy when it is available
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data.
nullable: true
migration_framework:
type: string
description: Framework used for applying migrations.
nullable: true
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- deletion_protected
- resizing
- resize_queued
- config_changing
- config_change_queued
- allow_data_branching
- foreign_keys_enabled
- restrict_branch_region
- prefer_instant
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- created_at
- updated_at
- schema_last_updated_at
- kind
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- 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`, `promote_branches`, `demote_branches`, `delete_production_branch`, `connect_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `delete_branch_password`, `delete_production_branch_password`, `delete_production_read_only_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_comment`, `create_comment`, `restore_backup`, `restore_production_branch_backup`, `read_backups`, `write_backups`, `delete_backups`, `delete_production_branch_backups`, `write_branch_vschema`, `write_production_branch_vschema`, `read_workflow`, `write_workflow`, `delete_workflow`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
post:
tags:
- Databases
operationId: create_database
summary: Create a database
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the database
region:
type: string
description: The region the database will be deployed in. If left blank, defaults to the organization's default region.
cluster_size:
type: string
description: The database cluster size name (e.g., 'PS_10', 'PS_80'). Use the 'List available cluster sizes' endpoint to get available options for your organization. /v1/organizations/:organization/cluster-size-skus
replicas:
type: integer
description: The number of replicas for the database. 0 for non-HA, 2+ for HA.
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database to create.
major_version:
type: string
description: For PostgreSQL databases, the PostgreSQL major version to use for the database. Defaults to the latest available major version.
storage:
type: object
properties:
minimum_storage_bytes:
type: integer
description: The initial minimum storage size in bytes.
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes for autoscaling.
required:
- name
- cluster_size
responses:
"201":
description: Returns the created database
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
branches_count:
type: integer
description: The total number of database branches
open_schema_recommendations_count:
type: integer
description: The total number of schema recommendations
development_branches_count:
type: integer
description: The total number of database development branches
production_branches_count:
type: integer
description: The total number of database production branches
issues_count:
type: integer
description: The total number of ongoing issues within a database
nullable: true
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: If the database has reached its backup restored branch limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
nullable: true
finished_at:
type: string
description: When the import finished
nullable: true
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
required:
- hostname
- port
- database
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: Whether an approval is required to deploy schema changes to this database
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
config_changing:
type: boolean
description: True if a config change is in progress
config_change_queued:
type: boolean
description: True if a config change is queued for maintenance window
allow_data_branching:
type: boolean
description: Whether seeding branches with data is enabled for all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: Whether to automatically manage Rails migrations during deploy requests.
nullable: true
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
prefer_instant:
type: boolean
description: Whether deploy requests default to instant deploy when it is available
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data.
nullable: true
migration_framework:
type: string
description: Framework used for applying migrations.
nullable: true
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- deletion_protected
- resizing
- resize_queued
- config_changing
- config_change_queued
- allow_data_branching
- foreign_keys_enabled
- restrict_branch_region
- prefer_instant
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- created_at
- updated_at
- schema_last_updated_at
- kind
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`create_databases`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `create_databases` |
/organizations/{organization}/databases/{database}:
get:
tags:
- Databases
operationId: get_database
summary: Get a database
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
responses:
"200":
description: Returns a database
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
branches_count:
type: integer
description: The total number of database branches
open_schema_recommendations_count:
type: integer
description: The total number of schema recommendations
development_branches_count:
type: integer
description: The total number of database development branches
production_branches_count:
type: integer
description: The total number of database production branches
issues_count:
type: integer
description: The total number of ongoing issues within a database
nullable: true
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: If the database has reached its backup restored branch limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
nullable: true
finished_at:
type: string
description: When the import finished
nullable: true
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
required:
- hostname
- port
- database
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: Whether an approval is required to deploy schema changes to this database
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
config_changing:
type: boolean
description: True if a config change is in progress
config_change_queued:
type: boolean
description: True if a config change is queued for maintenance window
allow_data_branching:
type: boolean
description: Whether seeding branches with data is enabled for all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: Whether to automatically manage Rails migrations during deploy requests.
nullable: true
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
prefer_instant:
type: boolean
description: Whether deploy requests default to instant deploy when it is available
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data.
nullable: true
migration_framework:
type: string
description: Framework used for applying migrations.
nullable: true
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- deletion_protected
- resizing
- resize_queued
- config_changing
- config_change_queued
- allow_data_branching
- foreign_keys_enabled
- restrict_branch_region
- prefer_instant
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- created_at
- updated_at
- schema_last_updated_at
- kind
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`, `delete_database`, `write_database`, `read_branch`, `delete_branch`, `create_branch`, `promote_branches`, `demote_branches`, `delete_production_branch`, `connect_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `delete_branch_password`, `delete_production_branch_password`, `delete_production_read_only_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_comment`, `create_comment`, `restore_backup`, `restore_production_branch_backup`, `read_backups`, `write_backups`, `delete_backups`, `delete_production_branch_backups`, `write_branch_vschema`, `write_production_branch_vschema`, `read_workflow`, `write_workflow`, `delete_workflow`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
patch:
tags:
- Databases
operationId: update_database_settings
summary: Update database settings
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
new_name:
type: string
description: The name to update the database to
automatic_migrations:
type: boolean
description: Whether or not to copy migration data to new branches and in deploy requests. (Vitess only)
migration_framework:
type: string
description: A migration framework to use on the database. (Vitess only)
migration_table_name:
type: string
description: Name of table to use as migration table for the database. (Vitess only)
require_approval_for_deploy:
type: boolean
description: Whether or not deploy requests must be approved by a database administrator other than the request creator
restrict_branch_region:
type: boolean
description: Whether or not to limit branch creation to the same region as the one selected during database creation.
allow_data_branching:
type: boolean
description: Whether or not data branching is allowed on the database. (Vitess only)
allow_foreign_key_constraints:
type: boolean
description: Whether or not foreign key constraints are allowed on the database. (Vitess only)
insights_raw_queries:
type: boolean
description: Whether or not full queries should be collected from the database
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the database
production_branch_web_console:
type: boolean
description: Whether or not the web console can be used on the production branch of the database
default_branch:
type: string
description: The default branch of the database
responses:
"200":
description: Returns the updated database
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
branches_count:
type: integer
description: The total number of database branches
open_schema_recommendations_count:
type: integer
description: The total number of schema recommendations
development_branches_count:
type: integer
description: The total number of database development branches
production_branches_count:
type: integer
description: The total number of database production branches
issues_count:
type: integer
description: The total number of ongoing issues within a database
nullable: true
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: If the database has reached its backup restored branch limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
nullable: true
finished_at:
type: string
description: When the import finished
nullable: true
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
required:
- hostname
- port
- database
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: Whether an approval is required to deploy schema changes to this database
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
config_changing:
type: boolean
description: True if a config change is in progress
config_change_queued:
type: boolean
description: True if a config change is queued for maintenance window
allow_data_branching:
type: boolean
description: Whether seeding branches with data is enabled for all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: Whether to automatically manage Rails migrations during deploy requests.
nullable: true
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
prefer_instant:
type: boolean
description: Whether deploy requests default to instant deploy when it is available
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data.
nullable: true
migration_framework:
type: string
description: Framework used for applying migrations.
nullable: true
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- deletion_protected
- resizing
- resize_queued
- config_changing
- config_change_queued
- allow_data_branching
- foreign_keys_enabled
- restrict_branch_region
- prefer_instant
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- created_at
- updated_at
- schema_last_updated_at
- kind
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
delete:
tags:
- Databases
operationId: delete_database
summary: Delete a database
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
responses:
"204":
description: Deletes a database
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`delete_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `delete_databases` |
| Database | `delete_database` |
/organizations/{organization}/databases/{database}/backup-policies:
get:
tags:
- BackupPolicies
operationId: list_backup_policies
summary: List backup policies
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns backup policies for the database
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_backups` |
| Database | `read_backups` |
post:
tags:
- BackupPolicies
operationId: create_backup_policy
summary: Create a backup policy
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
enum:
- hour
- day
- week
- month
- year
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
enum:
- hour
- day
- week
- month
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
responses:
"201":
description: Returns the created backup policy
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_backups` |
| Database | `write_backups` |
/organizations/{organization}/databases/{database}/backup-policies/{id}:
get:
tags:
- BackupPolicies
operationId: get_backup_policy
summary: Get a backup policy
parameters:
- name: id
in: path
required: true
description: The ID of the backup policy
schema:
type: string
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
responses:
"200":
description: Returns a backup policy
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_backups` |
| Database | `read_backups` |
patch:
tags:
- BackupPolicies
operationId: update_backup_policy
summary: Update a backup policy
parameters:
- name: id
in: path
required: true
description: The ID of the backup policy
schema:
type: string
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
enum:
- hour
- day
- week
- month
- year
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
enum:
- hour
- day
- week
- month
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
responses:
"200":
description: Returns the updated backup policy
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_backups` |
| Database | `write_backups` |
delete:
tags:
- BackupPolicies
operationId: delete_backup_policy
summary: Delete a backup policy
parameters:
- name: id
in: path
required: true
description: The ID of the backup policy
schema:
type: string
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
responses:
"204":
description: Returns no content
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_backups` |
| Database | `write_backups` |
/organizations/{organization}/databases/{database}/branches:
get:
tags:
- Database branches
operationId: list_branches
summary: List branches
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: q
in: query
description: Search branches by name
schema:
type: string
- name: production
in: query
description: Filter branches by production status
schema:
type: boolean
- name: safe_migrations
in: query
description: Filter branches by safe migrations (DDL protection)
schema:
type: boolean
- name: order
in: query
description: Order branches by created_at time
schema:
type: string
enum:
- asc
- desc
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns database branches
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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
nullable: true
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
nullable: true
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_name:
type: string
description: The public SKU representing the VTGate size
nullable: true
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
vtgate_autoscaling:
type: boolean
description: Whether VTGate autoscaling is enabled
vtgate_max_count:
type: integer
description: The maximum number of VTGate instances when autoscaling is enabled
nullable: true
vtgate_target_cpu_utilization:
type: integer
description: The target CPU utilization for VTGate autoscaling
nullable: true
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
nullable: true
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the branch
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
keyspace_count:
type: integer
description: The number of keyspaces in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
nullable: true
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_name
- vtgate_count
- vtgate_autoscaling
- vtgate_max_count
- vtgate_target_cpu_utilization
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- deletion_protected
- sharded
- shard_count
- keyspace_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
post:
tags:
- Database branches
operationId: create_branch
summary: Create a branch
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the branch to create
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the branch
parent_branch:
type: string
description: The name of the parent branch. Defaults to the database's default branch if not provided.
backup_id:
type: string
description: If provided, restores the backup's schema and data to the new branch. Must have `restore_production_branch_backup(s)` or `restore_backup(s)` access to do this.
region:
type: string
description: The region to create the branch in. If not provided, the branch will be created in the default region for its database.
restore_point:
type: string
description: Restore from a point-in-time recovery timestamp (e.g. 2023-01-01T00:00:00Z). Available only for PostgreSQL databases.
seed_data:
type: string
enum:
- last_successful_backup
description: If provided, restores the last successful backup's schema and data to the new branch. Must have `restore_production_branch_backup(s)` or `restore_backup(s)` access to do this, in addition to Data Branching™ being enabled for the branch.
cluster_size:
type: string
description: "The database cluster size. Required if a backup_id is provided (unless keyspace_cluster_sizes covers every keyspace), optional otherwise. Options: PS_10, PS_20, PS_40, ..., PS_2800"
keyspace_cluster_sizes:
type: array
items:
type: string
description: 'For MySQL backup restores, per-keyspace cluster sizes. Each entry is { "keyspace_name": "main", "cluster_size": "PS_40" }. When provided, each restored keyspace must have a size here or via cluster_size.'
storage:
type: object
properties:
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes.
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes for autoscaling.
major_version:
type: string
description: For PostgreSQL databases, the PostgreSQL major version to use for the branch. Defaults to the major version of the parent branch if it exists or the database's default branch major version. Ignored for branches restored from backups.
create_database_if_missing:
type: boolean
description: Create a new database for the branch if the database does not exist. Defaults to false.
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch to create. Required when create_database_if_missing is set.
required:
- name
responses:
"201":
description: Returns the created branch
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
nullable: true
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
nullable: true
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_name:
type: string
description: The public SKU representing the VTGate size
nullable: true
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
vtgate_autoscaling:
type: boolean
description: Whether VTGate autoscaling is enabled
vtgate_max_count:
type: integer
description: The maximum number of VTGate instances when autoscaling is enabled
nullable: true
vtgate_target_cpu_utilization:
type: integer
description: The target CPU utilization for VTGate autoscaling
nullable: true
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
nullable: true
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the branch
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
keyspace_count:
type: integer
description: The number of keyspaces in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
nullable: true
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_name
- vtgate_count
- vtgate_autoscaling
- vtgate_max_count
- vtgate_target_cpu_utilization
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- deletion_protected
- sharded
- shard_count
- keyspace_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`create_branch`, `restore_production_branch_backup`, `restore_backup`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_branches`, `restore_production_branch_backups`, `restore_backups` |
| Database | `write_branches`, `restore_production_branch_backups`, `restore_backups` |
| Branch | `restore_backups` |
/organizations/{organization}/databases/{database}/branches/{branch}:
get:
tags:
- Database branches
operationId: get_branch
summary: Get a branch
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
responses:
"200":
description: Returns information about a branch
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
nullable: true
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
nullable: true
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_name:
type: string
description: The public SKU representing the VTGate size
nullable: true
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
vtgate_autoscaling:
type: boolean
description: Whether VTGate autoscaling is enabled
vtgate_max_count:
type: integer
description: The maximum number of VTGate instances when autoscaling is enabled
nullable: true
vtgate_target_cpu_utilization:
type: integer
description: The target CPU utilization for VTGate autoscaling
nullable: true
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
nullable: true
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the branch
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
keyspace_count:
type: integer
description: The number of keyspaces in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
nullable: true
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_name
- vtgate_count
- vtgate_autoscaling
- vtgate_max_count
- vtgate_target_cpu_utilization
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- deletion_protected
- sharded
- shard_count
- keyspace_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
patch:
tags:
- Database branches
operationId: update_branch
summary: Update a branch
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
new_name:
type: string
description: The name to update the branch
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the branch
responses:
"200":
description: Returns the updated branch
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
nullable: true
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
nullable: true
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_name:
type: string
description: The public SKU representing the VTGate size
nullable: true
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
vtgate_autoscaling:
type: boolean
description: Whether VTGate autoscaling is enabled
vtgate_max_count:
type: integer
description: The maximum number of VTGate instances when autoscaling is enabled
nullable: true
vtgate_target_cpu_utilization:
type: integer
description: The target CPU utilization for VTGate autoscaling
nullable: true
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
nullable: true
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the branch
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
keyspace_count:
type: integer
description: The number of keyspaces in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
nullable: true
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_name
- vtgate_count
- vtgate_autoscaling
- vtgate_max_count
- vtgate_target_cpu_utilization
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- deletion_protected
- sharded
- shard_count
- keyspace_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_branches`, `write_databases` |
| Database | `write_branches`, `write_database` |
| Branch | `write_branch` |
delete:
tags:
- Database branches
operationId: delete_branch
summary: Delete a branch
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: delete_descendants
in: query
description: If true, recursively delete all descendant branches along with this branch
schema:
type: boolean
responses:
"204":
description: Delete a branch
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`delete_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `delete_branches`, `delete_production_branches` |
| Database | `delete_branches`, `delete_production_branches` |
| Branch | `delete_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/backups:
get:
tags:
- Backups
operationId: list_backups
summary: List backups
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: all
in: query
description: Whether to include all backups, including deleted ones
schema:
type: boolean
- name: state
in: query
description: Filter backups by state
schema:
type: string
enum:
- pending
- running
- success
- failed
- canceled
- ignored
- name: policy
in: query
description: Filter backups by backup policy ID
schema:
type: string
- name: from
in: query
description: Filter backups started after this date (e.g. 2023-01-01T00:00:00Z)
schema:
type: string
- name: to
in: query
description: Filter backups started before this date (e.g. 2023-01-31T23:59:59Z)
schema:
type: string
- name: running_at
in: query
description: Filter backups that are running during a specific time (e.g. 2023-01-01T00:00:00Z..2023-01-01T23:59:59Z)
schema:
type: string
- name: production
in: query
description: Filter backups by production branch
schema:
type: boolean
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns database branch backups
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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: integer
description: The size of the backup in bytes
estimated_storage_cost:
type: number
description: The estimated storage cost of the backup
created_at:
type: string
description: When the backup was created
updated_at:
type: string
description: When the backup was last updated
started_at:
type: string
description: When the backup started
nullable: true
expires_at:
type: string
description: When the backup expires
nullable: true
completed_at:
type: string
description: When the backup completed
nullable: true
deleted_at:
type: string
description: When the backup was deleted
nullable: true
pvc_size:
type: integer
description: Size of the PVC used for the backup
uncompressed_size:
type: integer
description: The uncompressed (logical) size of the backup in bytes
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
nullable: true
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
nullable: true
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
nullable: true
database_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- uncompressed_size
- protected
- required
- restored_branches
- actor
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_backups` |
| Database | `read_backups` |
| Branch | `read_backups` |
post:
tags:
- Backups
operationId: create_backup
summary: Create a backup
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name for the backup
retention_unit:
type: string
enum:
- hour
- day
- week
- month
- year
description: Unit for the retention period of the backup
retention_value:
type: integer
description: Value between `1` and `1000` for the retention period of the backup (i.e retention_value `6` and retention_unit `hour` means 6 hours)
emergency:
type: boolean
description: Whether the backup is an immediate backup that may affect database performance. Emergency backups are only supported for PostgreSQL databases.
responses:
"201":
description: Returns the created database branch backup
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the backup
name:
type: string
description: The name of the backup
state:
type: string
enum:
- pending
- running
- success
- failed
- canceled
- ignored
description: The current state of the backup
size:
type: integer
description: The size of the backup in bytes
estimated_storage_cost:
type: number
description: The estimated storage cost of the backup
created_at:
type: string
description: When the backup was created
updated_at:
type: string
description: When the backup was last updated
started_at:
type: string
description: When the backup started
nullable: true
expires_at:
type: string
description: When the backup expires
nullable: true
completed_at:
type: string
description: When the backup completed
nullable: true
deleted_at:
type: string
description: When the backup was deleted
nullable: true
pvc_size:
type: integer
description: Size of the PVC used for the backup
uncompressed_size:
type: integer
description: The uncompressed (logical) size of the backup in bytes
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
nullable: true
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
nullable: true
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
nullable: true
database_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- uncompressed_size
- protected
- required
- restored_branches
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_backups` |
| Database | `write_backups` |
| Branch | `write_backups` |
/organizations/{organization}/databases/{database}/branches/{branch}/backups/{id}:
get:
tags:
- Backups
operationId: get_backup
summary: Get a backup
parameters:
- name: id
in: path
required: true
description: The ID for the backup
schema:
type: string
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
"200":
description: Returns a database branch backup
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the backup
name:
type: string
description: The name of the backup
state:
type: string
enum:
- pending
- running
- success
- failed
- canceled
- ignored
description: The current state of the backup
size:
type: integer
description: The size of the backup in bytes
estimated_storage_cost:
type: number
description: The estimated storage cost of the backup
created_at:
type: string
description: When the backup was created
updated_at:
type: string
description: When the backup was last updated
started_at:
type: string
description: When the backup started
nullable: true
expires_at:
type: string
description: When the backup expires
nullable: true
completed_at:
type: string
description: When the backup completed
nullable: true
deleted_at:
type: string
description: When the backup was deleted
nullable: true
pvc_size:
type: integer
description: Size of the PVC used for the backup
uncompressed_size:
type: integer
description: The uncompressed (logical) size of the backup in bytes
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
nullable: true
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
nullable: true
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
nullable: true
database_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- uncompressed_size
- protected
- required
- restored_branches
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_backups` |
| Database | `read_backups` |
| Branch | `read_backups` |
patch:
tags:
- Backups
operationId: update_backup
summary: Update a backup
parameters:
- name: id
in: path
required: true
description: The ID of the backup
schema:
type: string
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
protected:
type: boolean
description: Whether the backup is protected from deletion or not
responses:
"200":
description: Returns the backup
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the backup
name:
type: string
description: The name of the backup
state:
type: string
enum:
- pending
- running
- success
- failed
- canceled
- ignored
description: The current state of the backup
size:
type: integer
description: The size of the backup in bytes
estimated_storage_cost:
type: number
description: The estimated storage cost of the backup
created_at:
type: string
description: When the backup was created
updated_at:
type: string
description: When the backup was last updated
started_at:
type: string
description: When the backup started
nullable: true
expires_at:
type: string
description: When the backup expires
nullable: true
completed_at:
type: string
description: When the backup completed
nullable: true
deleted_at:
type: string
description: When the backup was deleted
nullable: true
pvc_size:
type: integer
description: Size of the PVC used for the backup
uncompressed_size:
type: integer
description: The uncompressed (logical) size of the backup in bytes
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
nullable: true
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
nullable: true
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
nullable: true
database_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- uncompressed_size
- protected
- required
- restored_branches
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_backups` |
| Database | `write_backups` |
| Branch | `write_backups` |
delete:
tags:
- Backups
operationId: delete_backup
summary: Delete a backup
parameters:
- name: id
in: path
required: true
description: The ID of the backup
schema:
type: string
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
"204":
description: Delete a backup
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`delete_backups`, `delete_production_branch_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `delete_backups`, `delete_production_branch_backups` |
| Database | `delete_backups`, `delete_production_branch_backups` |
| Branch | `delete_backups` |
/organizations/{organization}/databases/{database}/branches/{branch}/bouncer-resizes:
get:
tags:
- api-branch_bouncer_resizes
operationId: list_branch_bouncer_resize_requests
summary: Get bouncer resize requests
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns bouncer resize requests
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer after the resize
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The backend target for the bouncer after the resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer before the resize
previous_target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The backend target for the bouncer before the resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
nullable: true
completed_at:
type: string
description: The time the bouncer resize completed
nullable: true
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
bouncer:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
required:
- id
- state
- replicas_per_cell
- target
- parameters
- previous_replicas_per_cell
- previous_target
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/bouncers:
get:
tags:
- Bouncers
operationId: list_bouncers
summary: List bouncers
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns bouncers
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer
name:
type: string
description: The name of the bouncer
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The instance type the bouncer targets
replicas_per_cell:
type: integer
description: The count of replicas in each cell
created_at:
type: string
description: When the bouncer was created
updated_at:
type: string
description: When the bouncer was updated
deleted_at:
type: string
description: When the bouncer was deleted
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
description: The namespace of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- namespace
- name
- display_name
- category
- description
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- url
- options
- actor
required:
- id
- name
- sku
- target
- replicas_per_cell
- created_at
- updated_at
- deleted_at
- actor
- branch
- parameters
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
post:
tags:
- Bouncers
operationId: create_bouncer
summary: Create a bouncer
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The bouncer name
target:
type: string
description: The type of server the bouncer targets
bouncer_size:
type: string
description: The size SKU for the bouncer
replicas_per_cell:
type: integer
description: The number of replica servers per cell
responses:
"200":
description: Returns the new bouncer
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the bouncer
name:
type: string
description: The name of the bouncer
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The instance type the bouncer targets
replicas_per_cell:
type: integer
description: The count of replicas in each cell
created_at:
type: string
description: When the bouncer was created
updated_at:
type: string
description: When the bouncer was updated
deleted_at:
type: string
description: When the bouncer was deleted
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
description: The namespace of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- namespace
- name
- display_name
- category
- description
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- url
- options
- actor
required:
- id
- name
- sku
- target
- replicas_per_cell
- created_at
- updated_at
- deleted_at
- actor
- branch
- parameters
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/bouncers/{bouncer}:
get:
tags:
- Bouncers
operationId: get_bouncer
summary: Get a bouncer
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: bouncer
in: path
required: true
description: The name of the bouncer
schema:
type: string
responses:
"200":
description: Returns a bouncer
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the bouncer
name:
type: string
description: The name of the bouncer
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The instance type the bouncer targets
replicas_per_cell:
type: integer
description: The count of replicas in each cell
created_at:
type: string
description: When the bouncer was created
updated_at:
type: string
description: When the bouncer was updated
deleted_at:
type: string
description: When the bouncer was deleted
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
description: The namespace of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- namespace
- name
- display_name
- category
- description
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- url
- options
- actor
required:
- id
- name
- sku
- target
- replicas_per_cell
- created_at
- updated_at
- deleted_at
- actor
- branch
- parameters
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
delete:
tags:
- Bouncers
operationId: delete_bouncer
summary: Delete a bouncer
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: bouncer
in: path
required: true
description: The name of the bouncer
schema:
type: string
responses:
"204":
description: Deletes the bouncer
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/bouncers/{bouncer}/resizes:
get:
tags:
- Bouncer resizes
operationId: list_bouncer_resize_requests
summary: Get bouncer resize requests
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: bouncer
in: path
required: true
description: The name of the bouncer
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns bouncer resize requests
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer after the resize
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The backend target for the bouncer after the resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer before the resize
previous_target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The backend target for the bouncer before the resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
nullable: true
completed_at:
type: string
description: The time the bouncer resize completed
nullable: true
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
bouncer:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
required:
- id
- state
- replicas_per_cell
- target
- parameters
- previous_replicas_per_cell
- previous_target
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
patch:
tags:
- Bouncer resizes
operationId: update_bouncer_resize_request
summary: Upsert a bouncer resize request
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: bouncer
in: path
required: true
description: The name of the bouncer
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
bouncer_size:
type: string
description: The bouncer size SKU name (e.g., 'PGB_5', 'PGB_10', 'PGB_20', 'PGB_40', 'PGB_80', 'PGB_160'). Defaults to 'PGB_5'.
replicas_per_cell:
type: integer
description: The number of PgBouncers per availability zone. Defaults to 1.
target:
type: string
description: The type of server the bouncer targets.
parameters:
type: object
additionalProperties: true
description: "Bouncer configuration parameters nested by namespace (e.g., {\"pgbouncer\": {\"default_pool_size\": \"100\"}}). Use the 'List cluster parameters' endpoint to retrieve available parameters. Only parameters with namespace 'pgbouncer' can be updated."
responses:
"200":
description: Returns bouncer resize request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer after the resize
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The backend target for the bouncer after the resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer before the resize
previous_target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The backend target for the bouncer before the resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
nullable: true
completed_at:
type: string
description: The time the bouncer resize completed
nullable: true
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
bouncer:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
required:
- id
- state
- replicas_per_cell
- target
- parameters
- previous_replicas_per_cell
- previous_target
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
delete:
tags:
- Bouncer resizes
operationId: cancel_bouncer_resize_request
summary: Cancel a resize request
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: bouncer
in: path
required: true
description: The name of the bouncer
schema:
type: string
responses:
"204":
description: Cancels a resize request
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/changes:
get:
tags:
- Branch changes
operationId: list_branch_change_requests
summary: Get branch change requests
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns branch change requests
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the branch change request
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
nullable: true
completed_at:
type: string
description: The time the branch change request completed
nullable: true
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
version:
type: string
description: The PostgreSQL version after the change
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: The previous SKU representing the branch cluster for display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_version:
type: string
description: The PostgreSQL version before the change
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: Whether storage shrinking is enabled when autoscaling is enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
- hyperdisk_balanced
- premium_v2_lrs
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
confirm_shrink:
type: boolean
description: Whether the change re-applies the current minimum disk size to shrink the provisioned disk
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- version
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_version
- 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
- confirm_shrink
required:
- type
- current_page
- per_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 for cluster size, replicas, storage, or parameters
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
cluster_size:
type: string
description: The size of the cluster. Available sizes can be found using the 'List cluster sizes' endpoint.
replicas:
type: integer
description: The total number of replicas
parameters:
type: object
additionalProperties: true
description: "Cluster configuration parameters nested by namespace (e.g., {\"pgconf\": {\"max_connections\": \"200\"}}). Use the 'List cluster parameters' endpoint to retrieve available parameters. Supported namespaces include 'patroni', 'pgconf', and 'pgbouncer'."
storage:
type: object
properties:
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes.
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes for autoscaling.
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled.
storage_iops:
type: integer
description: The storage IOPS.
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s.
confirm_shrink:
type: boolean
description: Re-apply the current minimum disk size to shrink the provisioned disk.
responses:
"200":
description: Returns the branch change request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch change request
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
nullable: true
completed_at:
type: string
description: The time the branch change request completed
nullable: true
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
version:
type: string
description: The PostgreSQL version after the change
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: The previous SKU representing the branch cluster for display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_version:
type: string
description: The PostgreSQL version before the change
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: Whether storage shrinking is enabled when autoscaling is enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
- hyperdisk_balanced
- premium_v2_lrs
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
confirm_shrink:
type: boolean
description: Whether the change re-applies the current minimum disk size to shrink the provisioned disk
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- version
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_version
- 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
- confirm_shrink
"204":
description: No changes to apply
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/changes/{id}:
get:
tags:
- Branch changes
operationId: get_branch_change_request
summary: Get a branch change request
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the change request
schema:
type: string
responses:
"200":
description: Returns a branch change request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch change request
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
nullable: true
completed_at:
type: string
description: The time the branch change request completed
nullable: true
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
version:
type: string
description: The PostgreSQL version after the change
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: The previous SKU representing the branch cluster for display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_version:
type: string
description: The PostgreSQL version before the change
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: Whether storage shrinking is enabled when autoscaling is enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
- hyperdisk_balanced
- premium_v2_lrs
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
confirm_shrink:
type: boolean
description: Whether the change re-applies the current minimum disk size to shrink the provisioned disk
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- version
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_version
- 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
- confirm_shrink
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/cluster:
patch:
tags:
- Database branches
operationId: update_branch_cluster_config
summary: Change a branch cluster configuration
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch to configure
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
cluster_size:
type: string
description: "The new size of the database cluster: PS_10, PS_20,…"
required:
- cluster_size
responses:
"204":
description: Returns an empty response body
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`write_database`
/organizations/{organization}/databases/{database}/branches/{branch}/demote:
post:
tags:
- Database branches
operationId: demote_branch
summary: Demote a branch
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
"200":
description: Returns a development branch
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
nullable: true
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
nullable: true
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_name:
type: string
description: The public SKU representing the VTGate size
nullable: true
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
vtgate_autoscaling:
type: boolean
description: Whether VTGate autoscaling is enabled
vtgate_max_count:
type: integer
description: The maximum number of VTGate instances when autoscaling is enabled
nullable: true
vtgate_target_cpu_utilization:
type: integer
description: The target CPU utilization for VTGate autoscaling
nullable: true
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
nullable: true
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the branch
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
keyspace_count:
type: integer
description: The number of keyspaces in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
nullable: true
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_name
- vtgate_count
- vtgate_autoscaling
- vtgate_max_count
- vtgate_target_cpu_utilization
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- deletion_protected
- sharded
- shard_count
- keyspace_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Demotes a branch from production to development
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`connect_production_branch`, `demote_branches`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `demote_branches` |
| Database | `demote_branches` |
/organizations/{organization}/databases/{database}/branches/{branch}/extensions:
get:
tags:
- Cluster extensions
operationId: list_extensions
summary: List cluster extensions
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
responses:
"200":
description: Returns cluster extensions
headers: {}
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the extension
name:
type: string
description: The name of the extension
description:
type: string
description: The description of the extension
internal:
type: boolean
description: The internal state of the extension
loader:
type: string
enum:
- shared_preload_libraries
- session_preload_libraries
- create_extension
description: How the extension is loaded
url:
type: string
description: The URL of the extension
available:
type: boolean
description: Whether the extension is available on the current cluster image
unavailable_reason:
type: string
description: The reason the extension is unavailable (e.g., 'container_upgrade_required')
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
namespace:
type: string
enum:
- patroni
- pgconf
- pgbouncer
description: The namespace of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
extension:
type: boolean
description: Configures an extension
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- seconds
- select
- string
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- name
- display_name
- namespace
- category
- description
- extension
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- url
- options
- actor
required:
- id
- name
- description
- internal
- loader
- url
- available
- unavailable_reason
- parameters
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/insights:
get:
tags:
- api-query_insights
operationId: list_branch_queries
summary: List branch queries
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: q
in: query
description: Search query statistics by SQL pattern
schema:
type: string
- name: from
in: query
description: Start time for filtering query statistics (ISO 8601 timestamp)
schema:
type: string
- name: to
in: query
description: End time for filtering query statistics (ISO 8601 timestamp)
schema:
type: string
- name: period
in: query
description: Time period for filtering query statistics
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
- name: sort
in: query
description: Field to sort by
schema:
type: string
enum:
- keyspace
- query
- lastRun
- count
- errorCount
- rowsRead
- rowsAffected
- rowsReturned
- rowsReadPerReturned
- rowsReadPerQuery
- rowsReturnedPerQuery
- rowsAffectedPerQuery
- totalTime
- cpuTime
- ioTime
- sumShardQueries
- maxShardQueries
- avgShardQueries
- avgParallelWorkers
- table
- qualifiedTable
- tableKeyspace
- indexes
- routingIndexes
- p50Latency
- p99Latency
- maxLatency
- percentTime
- percentCpuTime
- percentIoTime
- egressBytes
- egressBytesPerQuery
- maxEgressBytes
- ingressBytes
- ingressBytesPerQuery
- maxIngressBytes
- blocksRead
- blocksHit
- blockCacheHitRatio
- blocksDirtied
- blocksWritten
- trafficControlWarnings
- trafficControlThrottled
- trafficControlChecked
- trafficControlBudgetsUsed
- name: dir
in: query
description: Sort direction
schema:
type: string
enum:
- asc
- desc
- name: tablet_type
in: query
description: Filter by tablet type
schema:
type: string
enum:
- primary
- replica
- rdonly
- name: type
in: query
description: Filter by statement type
schema:
type: string
enum:
- SELECT
- INSERT
- UPDATE
- DELETE
- name: fields
in: query
description: Specific fields to include in the response
style: form
explode: false
schema:
type: array
items:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns query statistics summaries
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the query summary
fingerprint:
type: string
description: The query fingerprint
statement_type:
type: string
description: The type of SQL statement
keyspace:
type: string
description: The keyspace the query ran against
normalized_sql:
type: string
description: The normalized SQL statement
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL statement
multishard:
type: boolean
description: Whether the query is a multishard query
query_count:
type: integer
description: The number of times this query was executed
error_count:
type: integer
description: The number of times this query resulted in an error
tables:
items:
type: string
type: array
description: Tables accessed by the query
qualified_tables:
items:
type: string
type: array
description: Fully qualified tables accessed by the query
table_keyspaces:
items:
type: object
additionalProperties: true
type: array
description: Mapping of tables to their keyspaces
index_usages:
items:
type: object
additionalProperties: true
type: array
description: Index usage information
routing_index_usages:
items:
type: object
additionalProperties: true
type: array
description: Routing index usage information
sum_shard_queries:
type: integer
description: The total number of shard queries
max_shard_queries:
type: integer
description: The maximum number of shard queries for a single execution
avg_shard_queries:
type: number
description: The average number of shard queries
avg_parallel_workers:
type: number
description: The average number of parallel workers
sum_rows_read:
type: integer
description: The total number of rows read
sum_rows_affected:
type: integer
description: The total number of rows affected
sum_rows_returned:
type: integer
description: The total number of rows returned
rows_read_per_returned:
type: number
description: Average rows read per row returned
rows_read_per_query:
type: number
description: Average rows read per query
rows_returned_per_query:
type: number
description: Average rows returned per query
rows_affected_per_query:
type: number
description: Average rows affected per query
sum_total_duration_millis:
type: integer
description: Total duration in milliseconds across all executions
sum_total_duration_percent:
type: number
description: Percentage of total query time
sum_cpu_duration_millis:
type: integer
description: Total CPU duration in milliseconds
sum_cpu_duration_percent:
type: number
description: Percentage of total CPU time
sum_io_duration_millis:
type: integer
description: Total IO duration in milliseconds
sum_io_duration_percent:
type: number
description: Percentage of total IO time
last_run_at:
type: string
description: When this query was last executed
nullable: true
time_per_query:
type: number
description: Average time per query execution
p50_latency:
type: number
description: 50th percentile latency
p99_latency:
type: number
description: 99th percentile latency
max_latency:
type: number
description: Maximum latency observed
egress_bytes:
type: integer
description: Total egress bytes
egress_bytes_per_query:
type: number
description: Average egress bytes per query
max_egress_bytes:
type: integer
description: Maximum egress bytes for a single execution
ingress_bytes:
type: integer
description: Total ingress bytes
ingress_bytes_per_query:
type: number
description: Average ingress bytes per query
max_ingress_bytes:
type: integer
description: Maximum ingress bytes for a single execution
blocks_read:
type: integer
description: Total blocks read from disk
blocks_hit:
type: integer
description: Total blocks found in cache
block_cache_hit_ratio:
type: number
description: Cache hit ratio for blocks
blocks_dirtied:
type: integer
description: Total blocks dirtied
blocks_written:
type: integer
description: Total blocks written
traffic_control_warnings:
type: integer
description: The number of executions that triggered a traffic control warning
traffic_control_throttled:
type: integer
description: The number of executions throttled by traffic control
traffic_control_checked:
type: integer
description: The number of executions checked by traffic control rules
required:
- id
- fingerprint
- statement_type
- keyspace
- normalized_sql
- syntax_highlighted_sql
- multishard
- query_count
- error_count
- tables
- qualified_tables
- table_keyspaces
- index_usages
- routing_index_usages
- sum_shard_queries
- max_shard_queries
- avg_shard_queries
- avg_parallel_workers
- sum_rows_read
- sum_rows_affected
- sum_rows_returned
- rows_read_per_returned
- rows_read_per_query
- rows_returned_per_query
- rows_affected_per_query
- sum_total_duration_millis
- sum_total_duration_percent
- sum_cpu_duration_millis
- sum_cpu_duration_percent
- sum_io_duration_millis
- sum_io_duration_percent
- last_run_at
- time_per_query
- p50_latency
- p99_latency
- max_latency
- egress_bytes
- egress_bytes_per_query
- max_egress_bytes
- ingress_bytes
- ingress_bytes_per_query
- max_ingress_bytes
- blocks_read
- blocks_hit
- block_cache_hit_ratio
- blocks_dirtied
- blocks_written
- traffic_control_warnings
- traffic_control_throttled
- traffic_control_checked
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"400":
description: Invalid time range
"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_databases`, `read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/insights/anomalies:
get:
tags:
- api-anomalies
operationId: list_branch_anomalies
summary: List branch anomalies
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: from
in: query
description: Start time for filtering anomalies (ISO 8601 timestamp)
schema:
type: string
- name: to
in: query
description: End time for filtering anomalies (ISO 8601 timestamp)
schema:
type: string
- name: period
in: query
description: Time period for filtering anomalies
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns anomalies detected on the branch
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the anomaly
period_start:
type: string
description: When the anomaly started
period_end:
type: string
description: When the anomaly ended
minutes_in_violation:
type: integer
description: The number of minutes query latency was in violation of the expected baseline
active:
type: boolean
description: Whether the anomaly is ongoing
duration:
type: number
description: The duration of the anomaly in seconds
metrics_start:
type: string
description: Start of the metrics window surrounding the anomaly
metrics_end:
type: string
description: End of the metrics window surrounding the anomaly
correlations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the correlation
r:
type: number
description: The correlation coefficient between the query and the anomaly
keyspace:
type: string
description: The keyspace the query ran against
fingerprint:
type: string
description: The query fingerprint
normalized_sql:
type: string
description: The normalized SQL statement
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL statement
tablet_type:
type: string
enum:
- primary
- replica
- rdonly
description: The tablet type the query ran against
required:
- id
- r
- keyspace
- fingerprint
- normalized_sql
- syntax_highlighted_sql
- tablet_type
nullable: true
required:
- id
- period_start
- period_end
- minutes_in_violation
- active
- duration
- metrics_start
- metrics_end
required:
- type
- current_page
- per_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_databases`, `read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/insights/anomalies/{id}:
get:
tags:
- api-anomalies
operationId: get_branch_anomaly
summary: Retrieve a branch anomaly
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The anomaly ID
schema:
type: string
responses:
"200":
description: Returns the anomaly and its correlated queries
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the anomaly
period_start:
type: string
description: When the anomaly started
period_end:
type: string
description: When the anomaly ended
minutes_in_violation:
type: integer
description: The number of minutes query latency was in violation of the expected baseline
active:
type: boolean
description: Whether the anomaly is ongoing
duration:
type: number
description: The duration of the anomaly in seconds
metrics_start:
type: string
description: Start of the metrics window surrounding the anomaly
metrics_end:
type: string
description: End of the metrics window surrounding the anomaly
correlations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the correlation
r:
type: number
description: The correlation coefficient between the query and the anomaly
keyspace:
type: string
description: The keyspace the query ran against
fingerprint:
type: string
description: The query fingerprint
normalized_sql:
type: string
description: The normalized SQL statement
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL statement
tablet_type:
type: string
enum:
- primary
- replica
- rdonly
description: The tablet type the query ran against
required:
- id
- r
- keyspace
- fingerprint
- normalized_sql
- syntax_highlighted_sql
- tablet_type
nullable: true
required:
- id
- period_start
- period_end
- minutes_in_violation
- active
- duration
- metrics_start
- metrics_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_databases`, `read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/insights/errors:
get:
tags:
- api-query_insights_errors
operationId: list_branch_query_errors
summary: List branch query errors
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: q
in: query
description: Search query errors by error message
schema:
type: string
- name: from
in: query
description: Start time for filtering query errors (ISO 8601 timestamp)
schema:
type: string
- name: to
in: query
description: End time for filtering query errors (ISO 8601 timestamp)
schema:
type: string
- name: period
in: query
description: Time period for filtering query errors
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
- name: sort
in: query
description: Field to sort by
schema:
type: string
enum:
- error
- lastRun
- count
- totalTime
- timePerQuery
- name: dir
in: query
description: Sort direction
schema:
type: string
enum:
- asc
- desc
- name: tablet_type
in: query
description: Filter by tablet type
schema:
type: string
enum:
- primary
- replica
- rdonly
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns query error summaries
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the error summary
error_fingerprint:
type: string
description: The error fingerprint
started_at:
type: string
description: When the error last occurred
total_duration_millis:
type: integer
description: Total duration in milliseconds across all failed executions
time_per_query:
type: number
description: Average duration per failed execution in milliseconds
error_count:
type: integer
description: The number of times the error occurred
error_message:
type: string
description: The error message
required:
- id
- error_fingerprint
- started_at
- total_duration_millis
- time_per_query
- error_count
- error_message
required:
- type
- current_page
- per_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_databases`, `read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/insights/errors/{fingerprint}:
get:
tags:
- api-query_insights_errors
operationId: get_branch_query_error
summary: List queries for an error fingerprint
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: fingerprint
in: path
required: true
description: The error fingerprint
schema:
type: string
- name: from
in: query
description: Start time for filtering queries (ISO 8601 timestamp)
schema:
type: string
- name: to
in: query
description: End time for filtering queries (ISO 8601 timestamp)
schema:
type: string
- name: period
in: query
description: Time period for filtering queries
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns queries that failed with the given error fingerprint
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the query
password:
type: object
additionalProperties: true
description: The database password used for the query
tags:
items:
type: object
additionalProperties: true
type: array
description: Tags associated with the query
fingerprint:
type: string
description: The query fingerprint
started_at:
type: string
description: When the query started
nullable: true
statement_type:
type: string
description: The type of SQL statement
keyspace:
type: string
description: The keyspace the query ran against
tables:
items:
type: string
type: array
description: Tables accessed by the query
username:
type: string
description: The username that executed the query
remote_address:
type: string
description: The remote IP address of the client
shard_queries:
type: integer
description: The number of shard queries executed
rows_read:
type: integer
description: The number of rows read
rows_affected:
type: integer
description: The number of rows affected
rows_returned:
type: integer
description: The number of rows returned
total_duration_millis:
type: integer
description: Total query duration in milliseconds
error_message:
type: string
description: Error message if the query failed
normalized_sql:
type: string
description: The normalized SQL statement
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL statement
created_at:
type: string
description: When the query record was created
updated_at:
type: string
description: When the query record was last updated
explainable:
type: boolean
description: Whether the query can be explained
truncated:
type: boolean
description: Whether the query was truncated
required:
- id
- password
- tags
- fingerprint
- started_at
- statement_type
- keyspace
- tables
- username
- remote_address
- shard_queries
- rows_read
- rows_affected
- rows_returned
- total_duration_millis
- error_message
- normalized_sql
- syntax_highlighted_sql
- created_at
- updated_at
- explainable
- truncated
required:
- type
- current_page
- per_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_databases`, `read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/insights/queries/{id}:
get:
tags:
- api-query_insights
operationId: get_branch_query
summary: Retrieve a branch query
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The query ID
schema:
type: string
responses:
"200":
description: Returns a specific branch query
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the query
password:
type: object
additionalProperties: true
description: The database password used for the query
tags:
items:
type: object
additionalProperties: true
type: array
description: Tags associated with the query
fingerprint:
type: string
description: The query fingerprint
started_at:
type: string
description: When the query started
nullable: true
statement_type:
type: string
description: The type of SQL statement
keyspace:
type: string
description: The keyspace the query ran against
tables:
items:
type: string
type: array
description: Tables accessed by the query
username:
type: string
description: The username that executed the query
remote_address:
type: string
description: The remote IP address of the client
shard_queries:
type: integer
description: The number of shard queries executed
rows_read:
type: integer
description: The number of rows read
rows_affected:
type: integer
description: The number of rows affected
rows_returned:
type: integer
description: The number of rows returned
total_duration_millis:
type: integer
description: Total query duration in milliseconds
error_message:
type: string
description: Error message if the query failed
normalized_sql:
type: string
description: The normalized SQL statement
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL statement
created_at:
type: string
description: When the query record was created
updated_at:
type: string
description: When the query record was last updated
explainable:
type: boolean
description: Whether the query can be explained
truncated:
type: boolean
description: Whether the query was truncated
required:
- id
- password
- tags
- fingerprint
- started_at
- statement_type
- keyspace
- tables
- username
- remote_address
- shard_queries
- rows_read
- rows_affected
- rows_returned
- total_duration_millis
- error_message
- normalized_sql
- syntax_highlighted_sql
- created_at
- updated_at
- explainable
- truncated
"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_databases`, `read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/insights/tags:
get:
tags:
- api-query_insights_tags
operationId: list_branch_query_tags
summary: List query tags
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: q
in: query
description: Search tags by name
schema:
type: string
- name: from
in: query
description: Start time for filtering tags (ISO 8601 timestamp)
schema:
type: string
- name: to
in: query
description: End time for filtering tags (ISO 8601 timestamp)
schema:
type: string
- name: period
in: query
description: Time period for filtering tags
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
- name: fingerprint
in: query
description: Filter to tags on queries with this fingerprint
schema:
type: string
- name: keyspace
in: query
description: Filter by keyspace
schema:
type: string
- name: tablet_type
in: query
description: Filter by tablet type
schema:
type: string
enum:
- primary
- replica
- rdonly
- name: values_limit
in: query
description: Maximum number of values returned per tag (1-100)
schema:
type: integer
- name: literal_values_only
in: query
description: Only return literal tag values, excluding overflow and collapsed values
schema:
type: boolean
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns tags found on branch queries
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the tag
name:
type: string
description: The name of the tag
source:
type: string
enum:
- sql
- system
description: The source of the tag
query_count:
type: integer
description: The number of queries that have this tag
values:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the tag value
query_count:
type: integer
description: The number of queries that have this tag value
kind:
type: string
enum:
- literal
- overflow
- collapsed
description: The kind of tag value
required:
- name
- query_count
- kind
required:
- id
- name
- source
- query_count
- values
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"400":
description: Invalid time range
"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_databases`, `read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/insights/tags/summaries:
get:
tags:
- api-query_insights_tags
operationId: list_branch_query_tag_summaries
summary: List query statistics grouped by tag
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: tags
in: query
description: Tag ids returned by the tags list endpoint
style: form
explode: false
schema:
type: array
items:
type: string
- name: q
in: query
description: Search query statistics by SQL pattern
schema:
type: string
- name: from
in: query
description: Start time for filtering query statistics (ISO 8601 timestamp)
schema:
type: string
- name: to
in: query
description: End time for filtering query statistics (ISO 8601 timestamp)
schema:
type: string
- name: period
in: query
description: Time period for filtering query statistics
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
- name: sort
in: query
description: Field to sort by
schema:
type: string
enum:
- dimensions
- lastRun
- count
- errorCount
- rowsRead
- rowsAffected
- rowsReturned
- rowsReadPerReturned
- rowsReadPerQuery
- rowsReturnedPerQuery
- rowsAffectedPerQuery
- totalTime
- cpuTime
- ioTime
- sumShardQueries
- maxShardQueries
- avgShardQueries
- avgParallelWorkers
- table
- qualifiedTable
- tableKeyspace
- indexes
- routingIndexes
- p50Latency
- p99Latency
- maxLatency
- percentTime
- percentCpuTime
- percentIoTime
- egressBytes
- egressBytesPerQuery
- maxEgressBytes
- ingressBytes
- ingressBytesPerQuery
- maxIngressBytes
- blocksRead
- blocksHit
- blockCacheHitRatio
- blocksDirtied
- blocksWritten
- trafficControlWarnings
- trafficControlThrottled
- trafficControlChecked
- trafficControlBudgetsUsed
- name: dir
in: query
description: Sort direction
schema:
type: string
enum:
- asc
- desc
- name: tablet_type
in: query
description: Filter by tablet type
schema:
type: string
enum:
- primary
- replica
- rdonly
- name: type
in: query
description: Filter by statement type
schema:
type: string
enum:
- SELECT
- INSERT
- UPDATE
- DELETE
- name: fields
in: query
description: Specific fields to include in the response
style: form
explode: false
schema:
type: array
items:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns query statistics summaries grouped by tag
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
dimensions:
type: object
additionalProperties: true
description: The tag names and values this summary is grouped by
query_count:
type: integer
description: The number of times this query was executed
error_count:
type: integer
description: The number of times this query resulted in an error
tables:
items:
type: string
type: array
description: Tables accessed by the query
qualified_tables:
items:
type: string
type: array
description: Fully qualified tables accessed by the query
table_keyspaces:
items:
type: object
additionalProperties: true
type: array
description: Mapping of tables to their keyspaces
index_usages:
items:
type: object
additionalProperties: true
type: array
description: Index usage information
routing_index_usages:
items:
type: object
additionalProperties: true
type: array
description: Routing index usage information
sum_shard_queries:
type: integer
description: The total number of shard queries
max_shard_queries:
type: integer
description: The maximum number of shard queries for a single execution
avg_shard_queries:
type: number
description: The average number of shard queries
avg_parallel_workers:
type: number
description: The average number of parallel workers
sum_rows_read:
type: integer
description: The total number of rows read
sum_rows_affected:
type: integer
description: The total number of rows affected
sum_rows_returned:
type: integer
description: The total number of rows returned
rows_read_per_returned:
type: number
description: Average rows read per row returned
rows_read_per_query:
type: number
description: Average rows read per query
rows_returned_per_query:
type: number
description: Average rows returned per query
rows_affected_per_query:
type: number
description: Average rows affected per query
sum_total_duration_millis:
type: integer
description: Total duration in milliseconds across all executions
sum_total_duration_percent:
type: number
description: Percentage of total query time
sum_cpu_duration_millis:
type: integer
description: Total CPU duration in milliseconds
sum_cpu_duration_percent:
type: number
description: Percentage of total CPU time
sum_io_duration_millis:
type: integer
description: Total IO duration in milliseconds
sum_io_duration_percent:
type: number
description: Percentage of total IO time
last_run_at:
type: string
description: When this query was last executed
nullable: true
time_per_query:
type: number
description: Average time per query execution
p50_latency:
type: number
description: 50th percentile latency
p99_latency:
type: number
description: 99th percentile latency
max_latency:
type: number
description: Maximum latency observed
egress_bytes:
type: integer
description: Total egress bytes
egress_bytes_per_query:
type: number
description: Average egress bytes per query
max_egress_bytes:
type: integer
description: Maximum egress bytes for a single execution
ingress_bytes:
type: integer
description: Total ingress bytes
ingress_bytes_per_query:
type: number
description: Average ingress bytes per query
max_ingress_bytes:
type: integer
description: Maximum ingress bytes for a single execution
blocks_read:
type: integer
description: Total blocks read from disk
blocks_hit:
type: integer
description: Total blocks found in cache
block_cache_hit_ratio:
type: number
description: Cache hit ratio for blocks
blocks_dirtied:
type: integer
description: Total blocks dirtied
blocks_written:
type: integer
description: Total blocks written
traffic_control_warnings:
type: integer
description: The number of executions that triggered a traffic control warning
traffic_control_throttled:
type: integer
description: The number of executions throttled by traffic control
traffic_control_checked:
type: integer
description: The number of executions checked by traffic control rules
required:
- dimensions
- query_count
- error_count
- tables
- qualified_tables
- table_keyspaces
- index_usages
- routing_index_usages
- sum_shard_queries
- max_shard_queries
- avg_shard_queries
- avg_parallel_workers
- sum_rows_read
- sum_rows_affected
- sum_rows_returned
- rows_read_per_returned
- rows_read_per_query
- rows_returned_per_query
- rows_affected_per_query
- sum_total_duration_millis
- sum_total_duration_percent
- sum_cpu_duration_millis
- sum_cpu_duration_percent
- sum_io_duration_millis
- sum_io_duration_percent
- last_run_at
- time_per_query
- p50_latency
- p99_latency
- max_latency
- egress_bytes
- egress_bytes_per_query
- max_egress_bytes
- ingress_bytes
- ingress_bytes_per_query
- max_ingress_bytes
- blocks_read
- blocks_hit
- block_cache_hit_ratio
- blocks_dirtied
- blocks_written
- traffic_control_warnings
- traffic_control_throttled
- traffic_control_checked
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"400":
description: Invalid time range
"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_databases`, `read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/insights/tags/{tag}:
get:
tags:
- api-query_insights_tags
operationId: get_branch_query_tag
summary: Retrieve a query tag
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: tag
in: path
required: true
description: The tag name
schema:
type: string
- name: from
in: query
description: Start time for filtering tag values (ISO 8601 timestamp)
schema:
type: string
- name: to
in: query
description: End time for filtering tag values (ISO 8601 timestamp)
schema:
type: string
- name: period
in: query
description: Time period for filtering tag values
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
- name: fingerprint
in: query
description: Filter to tag values on queries with this fingerprint
schema:
type: string
- name: keyspace
in: query
description: Filter by keyspace
schema:
type: string
- name: tablet_type
in: query
description: Filter by tablet type
schema:
type: string
enum:
- primary
- replica
- rdonly
- name: values_limit
in: query
description: Maximum number of values returned (1-100)
schema:
type: integer
- name: literal_values_only
in: query
description: Only return literal tag values, excluding overflow and collapsed values
schema:
type: boolean
responses:
"200":
description: Returns the tag and its values
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the tag
name:
type: string
description: The name of the tag
source:
type: string
enum:
- sql
- system
description: The source of the tag
query_count:
type: integer
description: The number of queries that have this tag
values:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the tag value
query_count:
type: integer
description: The number of queries that have this tag value
kind:
type: string
enum:
- literal
- overflow
- collapsed
description: The kind of tag value
required:
- name
- query_count
- kind
required:
- id
- name
- source
- query_count
- values
"400":
description: Invalid time range
"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_databases`, `read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/insights/{fingerprint}:
get:
tags:
- api-query_insights
operationId: get_query_statistics
summary: Retrieve query statistics
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: fingerprint
in: path
required: true
description: The query fingerprint
schema:
type: string
- name: keyspace
in: query
required: true
description: The keyspace to filter by
schema:
type: string
- name: from
in: query
description: Start time for filtering query statistics (ISO 8601 timestamp)
schema:
type: string
- name: to
in: query
description: End time for filtering query statistics (ISO 8601 timestamp)
schema:
type: string
- name: period
in: query
description: Time period for filtering query statistics
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns detailed query statistics
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the query
password:
type: object
additionalProperties: true
description: The database password used for the query
tags:
items:
type: object
additionalProperties: true
type: array
description: Tags associated with the query
fingerprint:
type: string
description: The query fingerprint
started_at:
type: string
description: When the query started
nullable: true
statement_type:
type: string
description: The type of SQL statement
keyspace:
type: string
description: The keyspace the query ran against
tables:
items:
type: string
type: array
description: Tables accessed by the query
username:
type: string
description: The username that executed the query
remote_address:
type: string
description: The remote IP address of the client
shard_queries:
type: integer
description: The number of shard queries executed
rows_read:
type: integer
description: The number of rows read
rows_affected:
type: integer
description: The number of rows affected
rows_returned:
type: integer
description: The number of rows returned
total_duration_millis:
type: integer
description: Total query duration in milliseconds
error_message:
type: string
description: Error message if the query failed
normalized_sql:
type: string
description: The normalized SQL statement
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL statement
created_at:
type: string
description: When the query record was created
updated_at:
type: string
description: When the query record was last updated
explainable:
type: boolean
description: Whether the query can be explained
truncated:
type: boolean
description: Whether the query was truncated
required:
- id
- password
- tags
- fingerprint
- started_at
- statement_type
- keyspace
- tables
- username
- remote_address
- shard_queries
- rows_read
- rows_affected
- rows_returned
- total_duration_millis
- error_message
- normalized_sql
- syntax_highlighted_sql
- created_at
- updated_at
- explainable
- truncated
required:
- type
- current_page
- per_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_databases`, `read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/insights/{fingerprint}/summary:
get:
tags:
- api-query_insights
operationId: get_query_summary
summary: Retrieve a summary of query statistics
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: fingerprint
in: path
required: true
description: The query fingerprint
schema:
type: string
- name: keyspace
in: query
required: true
description: The keyspace to filter by
schema:
type: string
- name: from
in: query
description: Start time for filtering query statistics (ISO 8601 timestamp)
schema:
type: string
- name: to
in: query
description: End time for filtering query statistics (ISO 8601 timestamp)
schema:
type: string
- name: period
in: query
description: Time period for filtering query statistics
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
responses:
"200":
description: Returns aggregated query statistics summary
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the query summary
fingerprint:
type: string
description: The query fingerprint
statement_type:
type: string
description: The type of SQL statement
keyspace:
type: string
description: The keyspace the query ran against
normalized_sql:
type: string
description: The normalized SQL statement
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL statement
multishard:
type: boolean
description: Whether the query is a multishard query
query_count:
type: integer
description: The number of times this query was executed
error_count:
type: integer
description: The number of times this query resulted in an error
tables:
items:
type: string
type: array
description: Tables accessed by the query
qualified_tables:
items:
type: string
type: array
description: Fully qualified tables accessed by the query
table_keyspaces:
items:
type: object
additionalProperties: true
type: array
description: Mapping of tables to their keyspaces
index_usages:
items:
type: object
additionalProperties: true
type: array
description: Index usage information
routing_index_usages:
items:
type: object
additionalProperties: true
type: array
description: Routing index usage information
sum_shard_queries:
type: integer
description: The total number of shard queries
max_shard_queries:
type: integer
description: The maximum number of shard queries for a single execution
avg_shard_queries:
type: number
description: The average number of shard queries
avg_parallel_workers:
type: number
description: The average number of parallel workers
sum_rows_read:
type: integer
description: The total number of rows read
sum_rows_affected:
type: integer
description: The total number of rows affected
sum_rows_returned:
type: integer
description: The total number of rows returned
rows_read_per_returned:
type: number
description: Average rows read per row returned
rows_read_per_query:
type: number
description: Average rows read per query
rows_returned_per_query:
type: number
description: Average rows returned per query
rows_affected_per_query:
type: number
description: Average rows affected per query
sum_total_duration_millis:
type: integer
description: Total duration in milliseconds across all executions
sum_total_duration_percent:
type: number
description: Percentage of total query time
sum_cpu_duration_millis:
type: integer
description: Total CPU duration in milliseconds
sum_cpu_duration_percent:
type: number
description: Percentage of total CPU time
sum_io_duration_millis:
type: integer
description: Total IO duration in milliseconds
sum_io_duration_percent:
type: number
description: Percentage of total IO time
last_run_at:
type: string
description: When this query was last executed
nullable: true
time_per_query:
type: number
description: Average time per query execution
p50_latency:
type: number
description: 50th percentile latency
p99_latency:
type: number
description: 99th percentile latency
max_latency:
type: number
description: Maximum latency observed
egress_bytes:
type: integer
description: Total egress bytes
egress_bytes_per_query:
type: number
description: Average egress bytes per query
max_egress_bytes:
type: integer
description: Maximum egress bytes for a single execution
ingress_bytes:
type: integer
description: Total ingress bytes
ingress_bytes_per_query:
type: number
description: Average ingress bytes per query
max_ingress_bytes:
type: integer
description: Maximum ingress bytes for a single execution
blocks_read:
type: integer
description: Total blocks read from disk
blocks_hit:
type: integer
description: Total blocks found in cache
block_cache_hit_ratio:
type: number
description: Cache hit ratio for blocks
blocks_dirtied:
type: integer
description: Total blocks dirtied
blocks_written:
type: integer
description: Total blocks written
traffic_control_warnings:
type: integer
description: The number of executions that triggered a traffic control warning
traffic_control_throttled:
type: integer
description: The number of executions throttled by traffic control
traffic_control_checked:
type: integer
description: The number of executions checked by traffic control rules
required:
- id
- fingerprint
- statement_type
- keyspace
- normalized_sql
- syntax_highlighted_sql
- multishard
- query_count
- error_count
- tables
- qualified_tables
- table_keyspaces
- index_usages
- routing_index_usages
- sum_shard_queries
- max_shard_queries
- avg_shard_queries
- avg_parallel_workers
- sum_rows_read
- sum_rows_affected
- sum_rows_returned
- rows_read_per_returned
- rows_read_per_query
- rows_returned_per_query
- rows_affected_per_query
- sum_total_duration_millis
- sum_total_duration_percent
- sum_cpu_duration_millis
- sum_cpu_duration_percent
- sum_io_duration_millis
- sum_io_duration_percent
- last_run_at
- time_per_query
- p50_latency
- p99_latency
- max_latency
- egress_bytes
- egress_bytes_per_query
- max_egress_bytes
- ingress_bytes
- ingress_bytes_per_query
- max_ingress_bytes
- blocks_read
- blocks_hit
- block_cache_hit_ratio
- blocks_dirtied
- blocks_written
- traffic_control_warnings
- traffic_control_throttled
- traffic_control_checked
"400":
description: Invalid time range
"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_databases`, `read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/insights/{fingerprint}/traffic/budgets:
get:
tags:
- api-query_insights_traffic_budgets
operationId: list_traffic_budgets_for_query
summary: List traffic budgets affecting a query fingerprint
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: fingerprint
in: path
required: true
description: The query fingerprint
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
- name: keyspace
in: query
description: Optional keyspace filter
schema:
type: string
responses:
"200":
description: Returns the traffic budgets affecting the query fingerprint
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic budget
name:
type: string
description: The name of the budget
mode:
type: string
enum:
- enforce
- warn
- off
description: The mode of the budget
capacity:
type: number
description: The maximum capacity that can be banked, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
rate:
type: number
description: The rate at which capacity refills, as a percentage of server resources (0-100). Unlimited when not set.
nullable: true
burst:
type: number
description: The maximum capacity a single query can consume, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
concurrency:
type: number
description: The percentage of available worker processes this policy can use (0-100). Unlimited when not set.
nullable: true
warning_threshold:
type: number
description: A percentage of capacity, burst, or concurrency thresholds to emit warnings for enforced budgets (0-100).
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
rules:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
- each
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
created_at:
type: string
description: When the budget was created
updated_at:
type: string
description: When the budget was updated
required:
- id
- name
- mode
- actor
- rules
- created_at
- updated_at
required:
- type
- current_page
- per_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}/keyspaces:
get:
tags:
- Database branch keyspaces
operationId: list_keyspaces
summary: Get keyspaces
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns keyspaces
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_in_progress:
type: boolean
description: True if the keyspace has an unfinished resize request
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
config_change_in_progress:
type: boolean
description: Is the keyspace undergoing a config change
ready:
type: boolean
description: Is the keyspace provisioned and serving traffic
metal:
type: boolean
description: Is the keyspace running on metal instances
default:
type: boolean
description: Is this the default keyspace for the branch
imported:
type: boolean
description: Is this keyspace used in an import
vector_pool_allocation:
type: number
description: Percentage of buffer pool memory allocated to vector indexes
nullable: true
node_ttl_strategy:
type: string
enum:
- node_ttl_follow_maintenance
- node_ttl_always
- node_ttl_off
description: Controls when node TTL drains are allowed
replication_durability_constraints:
type: object
properties:
strategy:
type: string
enum:
- available
- lag
- always
description: The replication durability strategy
nullable: true
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_in_progress
- resize_pending
- config_change_in_progress
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
post:
tags:
- Database branch keyspaces
operationId: create_keyspace
summary: Create a keyspace
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the keyspace
cluster_size:
type: string
description: The database cluster size name (e.g., 'PS_10', 'PS_80'). Use the 'List available cluster sizes' endpoint to get available options for your organization. /v1/organizations/:organization/cluster-size-skus
extra_replicas:
type: integer
description: The number of additional replicas beyond the included default
shards:
type: integer
description: "The number of shards. Default: 1"
required:
- name
- cluster_size
responses:
"200":
description: Returns a created keyspace
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_in_progress:
type: boolean
description: True if the keyspace has an unfinished resize request
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
config_change_in_progress:
type: boolean
description: Is the keyspace undergoing a config change
ready:
type: boolean
description: Is the keyspace provisioned and serving traffic
metal:
type: boolean
description: Is the keyspace running on metal instances
default:
type: boolean
description: Is this the default keyspace for the branch
imported:
type: boolean
description: Is this keyspace used in an import
vector_pool_allocation:
type: number
description: Percentage of buffer pool memory allocated to vector indexes
nullable: true
node_ttl_strategy:
type: string
enum:
- node_ttl_follow_maintenance
- node_ttl_always
- node_ttl_off
description: Controls when node TTL drains are allowed
replication_durability_constraints:
type: object
properties:
strategy:
type: string
enum:
- available
- lag
- always
description: The replication durability strategy
nullable: true
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_in_progress
- resize_pending
- config_change_in_progress
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`create_branch`
/organizations/{organization}/databases/{database}/branches/{branch}/keyspaces/{keyspace}:
get:
tags:
- Database branch keyspaces
operationId: get_keyspace
summary: Get a keyspace
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
"200":
description: Returns information about a keyspace
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_in_progress:
type: boolean
description: True if the keyspace has an unfinished resize request
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
config_change_in_progress:
type: boolean
description: Is the keyspace undergoing a config change
ready:
type: boolean
description: Is the keyspace provisioned and serving traffic
metal:
type: boolean
description: Is the keyspace running on metal instances
default:
type: boolean
description: Is this the default keyspace for the branch
imported:
type: boolean
description: Is this keyspace used in an import
vector_pool_allocation:
type: number
description: Percentage of buffer pool memory allocated to vector indexes
nullable: true
node_ttl_strategy:
type: string
enum:
- node_ttl_follow_maintenance
- node_ttl_always
- node_ttl_off
description: Controls when node TTL drains are allowed
replication_durability_constraints:
type: object
properties:
strategy:
type: string
enum:
- available
- lag
- always
description: The replication durability strategy
nullable: true
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_in_progress
- resize_pending
- config_change_in_progress
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
patch:
tags:
- Database branch keyspaces
operationId: update_keyspace
summary: Configure keyspace settings
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
replication_durability_constraints:
type: object
properties:
strategy:
type: string
description: The replication durability 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
responses:
"200":
description: Returns the keyspace
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_in_progress:
type: boolean
description: True if the keyspace has an unfinished resize request
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
config_change_in_progress:
type: boolean
description: Is the keyspace undergoing a config change
ready:
type: boolean
description: Is the keyspace provisioned and serving traffic
metal:
type: boolean
description: Is the keyspace running on metal instances
default:
type: boolean
description: Is this the default keyspace for the branch
imported:
type: boolean
description: Is this keyspace used in an import
vector_pool_allocation:
type: number
description: Percentage of buffer pool memory allocated to vector indexes
nullable: true
node_ttl_strategy:
type: string
enum:
- node_ttl_follow_maintenance
- node_ttl_always
- node_ttl_off
description: Controls when node TTL drains are allowed
replication_durability_constraints:
type: object
properties:
strategy:
type: string
enum:
- available
- lag
- always
description: The replication durability strategy
nullable: true
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_in_progress
- resize_pending
- config_change_in_progress
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`create_branch`
delete:
tags:
- Database branch keyspaces
operationId: delete_keyspace
summary: Delete a keyspace
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
"204":
description: Delete a keyspace
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`delete_branch`, `delete_production_branch`
/organizations/{organization}/databases/{database}/branches/{branch}/keyspaces/{keyspace}/resizes:
get:
tags:
- Keyspace resizes
operationId: list_keyspace_resize_requests
summary: Get keyspace resize requests
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
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
- name: completed_at
in: query
description: Filter resize requests completed between two dates (e.g. 2023-01-01T:00:00:00Z..2023-01-31T:23:59:59Z)
schema:
type: string
responses:
"200":
description: Returns keyspaces resize requests
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the keyspace resize request
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
- queued
description: The state of the resize request
started_at:
type: string
description: When the resize request started
nullable: true
completed_at:
type: string
description: When the resize request completed
nullable: true
created_at:
type: string
description: When the resize request was created
updated_at:
type: string
description: When the resize request was last updated
extra_replicas:
type: integer
description: The number of extra replicas requested for the keyspace
vector_pool_allocation:
type: number
description: Percentage of buffer pool memory allocated to vector indexes
previous_vector_pool_allocation:
type: number
description: Previous percentage of buffer pool memory allocated to vector indexes
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
previous_cluster_name:
type: string
description: Previous SKU representing the keyspace cluster size
previous_cluster_display_name:
type: string
description: Previous SKU representing the keyspace cluster size for display
replicas:
type: integer
description: Total number of replicas in the keyspace after resize
previous_replicas:
type: integer
description: Total number of replicas in the keyspace before resize
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- extra_replicas
- vector_pool_allocation
- previous_vector_pool_allocation
- cluster_name
- cluster_display_name
- previous_cluster_name
- previous_cluster_display_name
- replicas
- previous_replicas
- actor
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
put:
tags:
- Keyspace resizes
operationId: update_keyspace_resize_request
summary: Upsert a resize request
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:
cluster_size:
type: string
description: "The size of the keyspace cluster: PS_10, PS_20,…"
extra_replicas:
type: integer
description: The number of additional replicas beyond the included default
vector_pool_allocation:
type: integer
description: The percentage of the buffer pool allocated to vector indexes
responses:
"200":
description: Returns keyspace resize request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the keyspace resize request
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
- queued
description: The state of the resize request
started_at:
type: string
description: When the resize request started
nullable: true
completed_at:
type: string
description: When the resize request completed
nullable: true
created_at:
type: string
description: When the resize request was created
updated_at:
type: string
description: When the resize request was last updated
extra_replicas:
type: integer
description: The number of extra replicas requested for the keyspace
vector_pool_allocation:
type: number
description: Percentage of buffer pool memory allocated to vector indexes
previous_vector_pool_allocation:
type: number
description: Previous percentage of buffer pool memory allocated to vector indexes
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
previous_cluster_name:
type: string
description: Previous SKU representing the keyspace cluster size
previous_cluster_display_name:
type: string
description: Previous SKU representing the keyspace cluster size for display
replicas:
type: integer
description: Total number of replicas in the keyspace after resize
previous_replicas:
type: integer
description: Total number of replicas in the keyspace before resize
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- extra_replicas
- vector_pool_allocation
- previous_vector_pool_allocation
- cluster_name
- cluster_display_name
- previous_cluster_name
- previous_cluster_display_name
- replicas
- previous_replicas
- actor
"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`
delete:
tags:
- Keyspace resizes
operationId: cancel_keyspace_resize_request
summary: Cancel a resize request
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
"204":
description: 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 must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`write_database`
/organizations/{organization}/databases/{database}/branches/{branch}/keyspaces/{keyspace}/resizes/{id}:
get:
tags:
- Keyspace resizes
operationId: get_keyspace_resize_request
summary: Get a keyspace resize request
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
- name: id
in: path
required: true
description: The ID of the resize request
schema:
type: string
responses:
"200":
description: Returns a keyspace resize request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the keyspace resize request
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
- queued
description: The state of the resize request
started_at:
type: string
description: When the resize request started
nullable: true
completed_at:
type: string
description: When the resize request completed
nullable: true
created_at:
type: string
description: When the resize request was created
updated_at:
type: string
description: When the resize request was last updated
extra_replicas:
type: integer
description: The number of extra replicas requested for the keyspace
vector_pool_allocation:
type: number
description: Percentage of buffer pool memory allocated to vector indexes
previous_vector_pool_allocation:
type: number
description: Previous percentage of buffer pool memory allocated to vector indexes
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
previous_cluster_name:
type: string
description: Previous SKU representing the keyspace cluster size
previous_cluster_display_name:
type: string
description: Previous SKU representing the keyspace cluster size for display
replicas:
type: integer
description: Total number of replicas in the keyspace after resize
previous_replicas:
type: integer
description: Total number of replicas in the keyspace before resize
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- extra_replicas
- vector_pool_allocation
- previous_vector_pool_allocation
- cluster_name
- cluster_display_name
- previous_cluster_name
- previous_cluster_display_name
- replicas
- previous_replicas
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
/organizations/{organization}/databases/{database}/branches/{branch}/keyspaces/{keyspace}/rollout-status:
get:
tags:
- Database branch keyspaces
operationId: get_keyspace_rollout_status
summary: Get keyspace rollout status
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
"200":
description: Returns information about a keyspace's rollout
headers: {}
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the keyspace
state:
type: string
description: The current state of the rollout at the keyspace level
shards:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the shard
last_rollout_started_at:
type: string
description: The time at which the rollout started
last_rollout_finished_at:
type: string
description: The time at which the rollout completed
state:
type: string
description: The current state of the rollout at the shard level
required:
- name
- last_rollout_started_at
- last_rollout_finished_at
- state
required:
- name
- state
- shards
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
/organizations/{organization}/databases/{database}/branches/{branch}/keyspaces/{keyspace}/vschema:
get:
tags:
- Keyspace VSchemas
operationId: get_keyspace_vschema
summary: Get the VSchema for the keyspace
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
"200":
description: Returns the VSchema for the keyspace
headers: {}
content:
application/json:
schema:
type: object
properties:
raw:
type: string
description: The keyspace's VSchema
required:
- raw
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
patch:
tags:
- Keyspace VSchemas
operationId: update_keyspace_vschema
summary: Update the VSchema for the keyspace
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
vschema:
type: string
description: The new VSchema for the keyspace
required:
- vschema
responses:
"200":
description: Returns the VSchema for the keyspace
headers: {}
content:
application/json:
schema:
type: object
properties:
raw:
type: string
description: The keyspace's VSchema
required:
- raw
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Content
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`write_production_branch_vschema`, `write_branch_vschema`
/organizations/{organization}/databases/{database}/branches/{branch}/maintenance:
post:
tags:
- api-branch_maintenances
operationId: run_branch_maintenance
summary: Run maintenance for a Postgres branch
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
update_postgres_minor_version:
type: boolean
description: Whether to upgrade the branch to the latest PostgreSQL minor version during maintenance.
responses:
"204":
description: Maintenance started
headers: {}
"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**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/metrics:
get:
tags:
- Metrics
operationId: get_branch_metrics
summary: Get time-series metrics
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: metrics
in: query
description: Metric names to retrieve. Pass as `metrics[]=name` (repeat for multiple), `metrics=name`, or a comma-separated list (`metrics=name,other`). Time range is `period` (for example `15m`) or ISO 8601 `from`/`to`.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- avg_parallel_workers
- avg_shard_queries
- block_cache_hit_ratio
- blocks_dirtied
- blocks_hit
- blocks_read
- blocks_written
- connections
- cpu_duration_millis
- egress_bytes
- egress_bytes_per_query
- ingress_bytes
- ingress_bytes_per_query
- io_duration_millis
- latency_max
- latency_p50
- latency_p95
- latency_p99
- latency_p999
- max_egress_bytes
- max_ingress_bytes
- max_shard_queries
- planetscale_dedicated_pgbouncer_cpu_usage
- planetscale_dedicated_pgbouncer_current_connections
- planetscale_dedicated_pgbouncer_memory_usage
- planetscale_edge_bytes_received
- planetscale_edge_bytes_received_rate
- planetscale_edge_bytes_sent
- planetscale_edge_bytes_sent_rate
- planetscale_pgbouncer_current_connections
- planetscale_pgbouncer_pools_client
- planetscale_pgbouncer_pools_server
- planetscale_pods_container_ooms
- planetscale_pods_cpu_util_percentages
- planetscale_pods_iops_total
- planetscale_pods_mem_util_percentages
- planetscale_primary_memory_active_cache_bytes
- planetscale_primary_memory_inactive_cache_bytes
- planetscale_primary_memory_mmap_bytes
- planetscale_primary_memory_rss_bytes
- planetscale_primary_pgbouncer_cpu_util_percentages
- planetscale_primary_pgbouncer_mem_util_percentages
- planetscale_primary_pods_cpu_util_percentages
- planetscale_primary_pods_iops_total
- planetscale_primary_pods_mem_util_percentages
- planetscale_primary_postgres_connection_state
- planetscale_primary_storage_usage
- planetscale_primary_xact_commit_rate
- planetscale_replica_lag_seconds
- planetscale_replica_memory_active_cache_bytes
- planetscale_replica_memory_inactive_cache_bytes
- planetscale_replica_memory_mmap_bytes
- planetscale_replica_memory_rss_bytes
- planetscale_replica_pgbouncer_cpu_util_percentages
- planetscale_replica_pgbouncer_current_connections
- planetscale_replica_pgbouncer_mem_util_percentages
- planetscale_replica_pods_cpu_util_percentages
- planetscale_replica_pods_iops_total
- planetscale_replica_pods_mem_util_percentages
- planetscale_replica_postgres_connection_state
- planetscale_replica_storage_usage_bytes
- planetscale_replica_volume_usage_percentages
- planetscale_replication_slot_max_wal_retained_bytes
- planetscale_replication_slots_lost
- planetscale_settings_max_slot_wal_keep_size_bytes
- planetscale_storage_usage_bytes
- planetscale_volume_usage_percentages
- planetscale_wal_archiver_failed_rate
- planetscale_wal_archiver_last_age_succeeded
- planetscale_wal_archiver_succeeded_rate
- planetscale_wal_size_bytes
- queries
- query_errors
- rows_affected_per_query
- rows_read
- rows_read_per_query
- rows_read_per_returned
- rows_returned
- rows_returned_per_query
- rows_written
- storage_per_table
- total_duration_millis
- traffic_control_throttled
- traffic_control_warnings
- violations
- vtgate_cpu_avg_by_az
- vtgate_cpu_by_az
- vtgate_latency_p50
- vtgate_latency_p95
- vtgate_memory_avg_by_az
- vtgate_memory_by_az
- vtgate_requests
- name: period
in: query
description: Named time period to retrieve. Defaults to 12h.
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
- name: from
in: query
description: Start of a custom time range as an ISO 8601 timestamp
schema:
type: string
- name: to
in: query
description: End of a custom time range as an ISO 8601 timestamp
schema:
type: string
- name: steps
in: query
description: Number of data points to return
schema:
type: integer
- name: tablet_type
in: query
description: Filter by tablet type
schema:
type: string
enum:
- primary
- replica
- rdonly
- name: keyspace
in: query
description: Filter by keyspace
schema:
type: string
- name: shard
in: query
description: Filter by shard
schema:
type: string
- name: role
in: query
description: Filter by Postgres role
schema:
type: string
- name: container
in: query
description: Filter by container
schema:
type: string
- name: pod
in: query
description: Filter by pod
schema:
type: string
- name: pods
in: query
description: Filter by pods
style: form
explode: false
schema:
type: array
items:
type: string
- name: query_ids
in: query
description: Filter by query pattern IDs
style: form
explode: false
schema:
type: array
items:
type: string
- name: fingerprint
in: query
description: Filter by query fingerprint
schema:
type: string
- name: budget_id
in: query
description: Filter by traffic budget ID
schema:
type: string
- name: rule_id
in: query
description: Filter by traffic rule ID
schema:
type: string
- name: q
in: query
description: Filter by search terms
schema:
type: string
responses:
"200":
description: Returns time-series metrics
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The metrics response type
start_date:
type: string
description: The start of the time range
end_date:
type: string
description: The end of the time range
interval:
type: integer
description: The step interval in seconds between data points
series:
items:
type: string
type: array
required:
- type
- start_date
- end_date
- interval
- series
"400":
description: Malformed metrics parameter
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
"503":
description: Metrics service unavailable
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}/metrics/instant:
get:
tags:
- Metrics
operationId: get_instant_branch_metrics
summary: Get current metric values
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: metrics
in: query
description: Metric names to retrieve. Pass as `metrics[]=name` (repeat for multiple), `metrics=name`, or a comma-separated list (`metrics=name,other`).
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- planetscale_backup_fetch_percent
- planetscale_backup_restore_active
- planetscale_dedicated_pgbouncer_cpu_usage
- planetscale_dedicated_pgbouncer_current_client_connections
- planetscale_dedicated_pgbouncer_current_connections
- planetscale_dedicated_pgbouncer_current_server_connections
- planetscale_dedicated_pgbouncer_max_connections
- planetscale_dedicated_pgbouncer_memory_usage
- planetscale_pgbouncer_current_client_connections
- planetscale_pgbouncer_current_server_connections
- planetscale_pgbouncer_settings_max_client_conn
- planetscale_postgres_connection_state
- planetscale_postgres_settings_max_connections
- planetscale_volume_capacity_bytes
- planetscale_volume_disk_usage_bytes
- planetscale_volume_usage_percentage
- name: role
in: query
description: Filter by Postgres role
schema:
type: string
- name: shard
in: query
description: Filter by shard
schema:
type: string
- name: container
in: query
description: Filter by container
schema:
type: string
- name: pod
in: query
description: Filter by pod
schema:
type: string
responses:
"200":
description: Returns current metrics
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The metrics response type
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
required:
- id
- name
- created_at
- updated_at
- deleted_at
metrics:
type: array
items:
type: object
properties:
metric:
type: string
description: The metric name
label:
type: string
description: A human-readable metric label
values:
type: array
items:
type: object
properties:
pod:
type: string
description: Pod name
role:
type: string
description: Postgres role (primary or replica)
value:
type: number
description: Current metric value
required:
- pod
- role
- value
required:
- metric
- label
- values
required:
- type
- branch
- metrics
"400":
description: Malformed metrics parameter
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
"503":
description: Metrics service unavailable
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}/metrics/keyspace-tables:
get:
tags:
- Metrics
operationId: get_branch_keyspace_table_metrics
summary: Get table storage metrics by keyspace
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
responses:
"200":
description: Returns storage metrics keyed by keyspace and table name
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`, `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}/metrics/query:
get:
tags:
- Metrics
operationId: get_branch_query_metrics
summary: Get time-series metrics for SQL queries
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: metrics
in: query
description: Metric names to retrieve. Pass as `metrics[]=name` (repeat for multiple), `metrics=name`, or a comma-separated list (`metrics=name,other`). Time range is `period` (for example `15m`) or ISO 8601 `from`/`to`.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- avg_parallel_workers
- avg_shard_queries
- block_cache_hit_ratio
- blocks_dirtied
- blocks_hit
- blocks_read
- blocks_written
- cpu_duration_millis
- egress_bytes
- egress_bytes_per_query
- index_usage_percent
- ingress_bytes
- ingress_bytes_per_query
- io_duration_millis
- latency_max
- latency_min
- latency_p50
- latency_p95
- latency_p99
- latency_p999
- max_egress_bytes
- max_ingress_bytes
- max_shard_queries
- plan_change_score
- queries
- query_errors
- routing_index_usage_percent
- rows_affected_per_query
- rows_read
- rows_read_per_query
- rows_read_per_returned
- rows_returned
- rows_returned_per_query
- rows_written
- total_duration_millis
- traffic_control_throttled
- traffic_control_warnings
- name: query_ids
in: query
description: Query pattern IDs to retrieve metrics for
style: form
explode: false
schema:
type: array
items:
type: string
- name: fingerprint
in: query
description: Filter by query fingerprint
schema:
type: string
- name: keyspace
in: query
description: Keyspace for the query fingerprint
schema:
type: string
- name: period
in: query
description: Named time period to retrieve. Defaults to 12h.
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
- name: from
in: query
description: Start of a custom time range as an ISO 8601 timestamp
schema:
type: string
- name: to
in: query
description: End of a custom time range as an ISO 8601 timestamp
schema:
type: string
- name: steps
in: query
description: Number of data points to return
schema:
type: integer
- name: tablet_type
in: query
description: Filter by tablet type
schema:
type: string
enum:
- primary
- replica
- rdonly
- name: budget_id
in: query
description: Filter by traffic budget ID
schema:
type: string
- name: rule_id
in: query
description: Filter by traffic rule ID
schema:
type: string
- name: q
in: query
description: Filter by search terms
schema:
type: string
responses:
"200":
description: Returns time-series metrics for SQL queries
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The metrics response type
start_date:
type: string
description: The start of the time range
end_date:
type: string
description: The end of the time range
interval:
type: integer
description: The step interval in seconds between data points
series:
items:
type: string
type: array
required:
- type
- start_date
- end_date
- interval
- series
"400":
description: Malformed metrics parameter
"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}/metrics/tables:
get:
tags:
- Metrics
operationId: get_branch_table_metrics
summary: Get table storage metrics
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
responses:
"200":
description: Returns storage metrics keyed by table name
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`, `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}/metrics/tablets:
get:
tags:
- Metrics
operationId: get_tablet_metrics
summary: Get time-series tablet metrics
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: metrics
in: query
description: Metric names to retrieve. Pass as `metrics[]=name` (repeat for multiple), `metrics=name`, or a comma-separated list (`metrics=name,other`). Time range is `period` (for example `15m`) or ISO 8601 `from`/`to`.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- replication_lag
- vreplication_lag
- pod_cpu_usage
- pod_memory_usage
- pod_queries
- pod_rows_read
- pod_iops
- pod_ooms
- primary_cpu_usage
- primary_memory_usage
- primary_iops
- primary_queries
- primary_rows_read
- primary_rows_written
- shard_storage_usage
- shard_storage_available
- name: period
in: query
description: Named time period to retrieve. Defaults to 12h.
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
- name: from
in: query
description: Start of a custom time range as an ISO 8601 timestamp
schema:
type: string
- name: to
in: query
description: End of a custom time range as an ISO 8601 timestamp
schema:
type: string
- name: steps
in: query
description: Number of data points to return
schema:
type: integer
- name: keyspace
in: query
description: Filter by keyspace
schema:
type: string
- name: shard
in: query
description: Filter by shard
schema:
type: string
- name: pod
in: query
description: Filter by pod
schema:
type: string
- name: workflow
in: query
description: Filter by workflow ID
schema:
type: string
responses:
"200":
description: Returns time-series tablet metrics
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The metrics response type
start_date:
type: string
description: The start of the time range
end_date:
type: string
description: The end of the time range
interval:
type: integer
description: The step interval in seconds between data points
series:
items:
type: string
type: array
required:
- type
- start_date
- end_date
- interval
- series
"400":
description: Malformed metrics parameter
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
"503":
description: Metrics service unavailable
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}/metrics/tablets-instant:
get:
tags:
- Metrics
operationId: get_instant_tablet_metrics
summary: Get current tablet metrics
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: metrics
in: query
description: Metric names to retrieve. Pass as `metrics[]=name` (repeat for multiple), `metrics=name`, or a comma-separated list (`metrics=name,other`).
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- replication_lag
- primary_cpu_usage
- primary_memory_usage
- vtgate_cpu_usage
- vtgate_memory_usage
- name: keyspace
in: query
description: Filter by keyspace
schema:
type: string
- name: shard
in: query
description: Filter by shard
schema:
type: string
responses:
"200":
description: Returns current tablet metrics
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The metrics response type
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
required:
- id
- name
- created_at
- updated_at
- deleted_at
metrics:
type: array
items:
type: object
properties:
metric:
type: string
description: The metric name
label:
type: string
description: A human-readable metric label
values:
type: array
items:
type: object
properties:
pod:
type: string
description: Pod name
role:
type: string
description: Postgres role (primary or replica)
value:
type: number
description: Current metric value
required:
- pod
- role
- value
required:
- metric
- label
- values
required:
- type
- branch
- metrics
"400":
description: Malformed metrics parameter
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
"503":
description: Metrics service unavailable
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}/metrics/tag:
get:
tags:
- Metrics
operationId: get_branch_tag_metrics
summary: Get time-series metrics grouped by query tags
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: metrics
in: query
description: Metric names to retrieve. Pass as `metrics[]=name` (repeat for multiple), `metrics=name`, or a comma-separated list (`metrics=name,other`). Time range is `period` (for example `15m`) or ISO 8601 `from`/`to`.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- avg_parallel_workers
- avg_shard_queries
- block_cache_hit_ratio
- blocks_dirtied
- blocks_hit
- blocks_read
- blocks_written
- cpu_duration_millis
- egress_bytes
- egress_bytes_per_query
- ingress_bytes
- ingress_bytes_per_query
- io_duration_millis
- latency_max
- latency_min
- latency_p50
- latency_p95
- latency_p99
- latency_p999
- max_egress_bytes
- max_ingress_bytes
- max_shard_queries
- queries
- query_errors
- rows_affected_per_query
- rows_read
- rows_read_per_query
- rows_read_per_returned
- rows_returned
- rows_returned_per_query
- rows_written
- total_duration_millis
- traffic_control_throttled
- traffic_control_warnings
- name: tag_sets
in: query
description: Tag sets to retrieve metrics for
style: form
explode: false
schema:
type: array
items:
type: string
- name: period
in: query
description: Named time period to retrieve. Defaults to 12h.
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
- name: from
in: query
description: Start of a custom time range as an ISO 8601 timestamp
schema:
type: string
- name: to
in: query
description: End of a custom time range as an ISO 8601 timestamp
schema:
type: string
- name: steps
in: query
description: Number of data points to return
schema:
type: integer
- name: tablet_type
in: query
description: Filter by tablet type
schema:
type: string
enum:
- primary
- replica
- rdonly
- name: budget_id
in: query
description: Filter by traffic budget ID
schema:
type: string
- name: rule_id
in: query
description: Filter by traffic rule ID
schema:
type: string
- name: q
in: query
description: Filter by search terms
schema:
type: string
responses:
"200":
description: Returns time-series metrics grouped by query tags
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The metrics response type
start_date:
type: string
description: The start of the time range
end_date:
type: string
description: The end of the time range
interval:
type: integer
description: The step interval in seconds between data points
series:
items:
type: string
type: array
required:
- type
- start_date
- end_date
- interval
- series
"400":
description: Invalid tag filter or malformed metrics parameter
"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}/parameters:
get:
tags:
- Cluster parameters
operationId: list_parameters
summary: List cluster parameters
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
responses:
"200":
description: Returns cluster parameters
headers: {}
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
namespace:
type: string
enum:
- patroni
- pgconf
- pgbouncer
description: The namespace of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
extension:
type: boolean
description: Configures an extension
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- seconds
- select
- string
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- name
- display_name
- namespace
- category
- description
- extension
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- url
- options
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |2-
Returns the parameters for a branch. To update the parameters, use the "update_branch_change_request" endpoint.
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/passwords:
get:
tags:
- Database branch passwords
operationId: list_passwords
summary: List passwords
parameters:
- name: organization
in: path
required: true
description: The name of the organization the password belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the password belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch the password belongs to
schema:
type: string
- name: read_only_region_id
in: query
description: A read-only region of the database branch. If present, the password results will be filtered to only those in the region
schema:
type: string
- name: status
in: query
description: Filter passwords by status
schema:
type: string
- name: q
in: query
description: Search passwords by name
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns passwords for the branch
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: The list of hosts in each availability zone providing direct access to a vtgate
ttl_seconds:
type: integer
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plaintext password. Null except in the response from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
post:
tags:
- Database branch passwords
operationId: create_password
summary: Create a password
parameters:
- name: organization
in: path
required: true
description: The name of the organization the password belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the password belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch the password belongs to
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Optional name of the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The database role of the password (i.e. admin)
replica:
type: boolean
description: Whether the password is for a read replica
ttl:
type: integer
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
cidrs:
type: array
items:
type: string
description: List of IP addresses or CIDR ranges that can use this password
direct_vtgate:
type: boolean
description: Whether the password connects directly to a VTGate
responses:
"201":
description: Returns the new credentials
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: The list of hosts in each availability zone providing direct access to a vtgate
ttl_seconds:
type: integer
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plaintext password. Null except in the response from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Content
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/passwords/{id}:
get:
tags:
- Database branch passwords
operationId: get_password
summary: Get a password
parameters:
- name: organization
in: path
required: true
description: The name of the organization the password belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the password belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch the password belongs to
schema:
type: string
- name: id
in: path
required: true
description: The ID of the password
schema:
type: string
responses:
"200":
description: Returns a password
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: The list of hosts in each availability zone providing direct access to a vtgate
ttl_seconds:
type: integer
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plaintext password. Null except in the response from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
patch:
tags:
- Database branch passwords
operationId: update_password
summary: Update a password
parameters:
- name: organization
in: path
required: true
description: The name of the organization the password belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the password belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch the password belongs to
schema:
type: string
- name: id
in: path
required: true
description: The ID of the password
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name for the password
cidrs:
type: array
items:
type: string
description: List of IP addresses or CIDR ranges that can use this password
responses:
"200":
description: Returns the updated password
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: The list of hosts in each availability zone providing direct access to a vtgate
ttl_seconds:
type: integer
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plaintext password. Null except in the response from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
delete:
tags:
- Database branch passwords
operationId: delete_password
summary: Delete a password
parameters:
- name: organization
in: path
required: true
description: The name of the organization the password belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the password belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch the password belongs to
schema:
type: string
- name: id
in: path
required: true
description: The ID of the password
schema:
type: string
responses:
"204":
description: Deletes the password
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`delete_production_branch_password`, `delete_production_read_only_branch_password`, `delete_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/passwords/{id}/renew:
post:
tags:
- Database branch passwords
operationId: renew_password
summary: Renew a password
parameters:
- name: organization
in: path
required: true
description: The name of the organization the password belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the password belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch the password belongs to
schema:
type: string
- name: id
in: path
required: true
description: The ID of the password
schema:
type: string
responses:
"200":
description: Returns the renewed password
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: The list of hosts in each availability zone providing direct access to a vtgate
ttl_seconds:
type: integer
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plaintext password. Null except in the response from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/promote:
post:
tags:
- Database branches
operationId: promote_branch
summary: Promote a branch
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
"200":
description: Returns a production branch
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
nullable: true
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
nullable: true
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_name:
type: string
description: The public SKU representing the VTGate size
nullable: true
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
vtgate_autoscaling:
type: boolean
description: Whether VTGate autoscaling is enabled
vtgate_max_count:
type: integer
description: The maximum number of VTGate instances when autoscaling is enabled
nullable: true
vtgate_target_cpu_utilization:
type: integer
description: The target CPU utilization for VTGate autoscaling
nullable: true
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
nullable: true
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the branch
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
keyspace_count:
type: integer
description: The number of keyspaces in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
nullable: true
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_name
- vtgate_count
- vtgate_autoscaling
- vtgate_max_count
- vtgate_target_cpu_utilization
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- deletion_protected
- sharded
- shard_count
- keyspace_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Promotes a branch from development to production
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`connect_production_branch`, `promote_branches`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `promote_branches` |
| Database | `promote_branches` |
/organizations/{organization}/databases/{database}/branches/{branch}/query-patterns:
get:
tags:
- Query Insights reports
operationId: list_generated_query_patterns_reports
summary: List generated query patterns reports
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: starting_after
in: query
description: If provided, returns results after the specified cursor
schema:
type: string
- name: ending_before
in: query
description: If provided, returns results before the specified cursor
schema:
type: string
- name: limit
in: query
description: If provided, specifies the number of returned results (max 100)
schema:
type: integer
default: 25
responses:
"200":
description: Returns the generated query patterns reports
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
has_next:
type: boolean
description: Whether there is a next page of results
has_prev:
type: boolean
description: Whether there is a previous page of results
cursor_start:
type: string
description: The ID of the first object in the current results, or null when there are no results
nullable: true
cursor_end:
type: string
description: The ID of the last object in the current results, or null when there are no results
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
nullable: true
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- created_at
- finished_at
- url
- download_url
- actor
required:
- type
- has_next
- has_prev
- cursor_start
- cursor_end
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
post:
tags:
- Query Insights reports
operationId: create_query_patterns_report
summary: Create a new query patterns report
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
"201":
description: The created query patterns download
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
nullable: true
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- created_at
- finished_at
- url
- download_url
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/query-patterns/{id}:
get:
tags:
- Query Insights reports
operationId: get_query_patterns_report_status
summary: Show the status of a query patterns report
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: id
in: path
required: true
description: The ID of the query patterns report
schema:
type: string
responses:
"200":
description: The retrieved query patterns download
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
nullable: true
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- created_at
- finished_at
- url
- download_url
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
delete:
tags:
- Query Insights reports
operationId: delete_query_patterns_report
summary: Delete a query patterns report
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: id
in: path
required: true
description: The ID of the query patterns report
schema:
type: string
responses:
"204":
description: Delete a query patterns report
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/query-patterns/{id}/download:
get:
tags:
- Query Insights reports
operationId: get_query_patterns_report
summary: Download a finished query patterns report
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: id
in: path
required: true
description: The ID of the query patterns report
schema:
type: string
responses:
"302":
description: Redirect to the query patterns download
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
nullable: true
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- created_at
- finished_at
- url
- download_url
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/read-only-replica-changes:
get:
tags:
- api-read_only_replica_changes
operationId: list_read_only_replica_change_requests
summary: Get read-only replica change requests
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
- name: period
in: query
description: Filter change requests by named period
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
- name: completed_at
in: query
description: Filter change requests completed between two ISO 8601 timestamps
schema:
type: string
responses:
"200":
description: Returns read-only replica change requests
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the read-only replica change request
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the change request
cluster_name:
type: string
description: The new cluster size SKU
cluster_display_name:
type: string
description: The new cluster size for display
cluster_rank:
type: integer
description: The new cluster size sort order
replicas:
type: integer
description: The new instance count
parameters:
type: object
additionalProperties: true
description: The new parameters
previous_cluster_name:
type: string
description: The previous cluster size SKU
previous_cluster_display_name:
type: string
description: The previous cluster size for display
previous_cluster_rank:
type: integer
description: The previous cluster size sort order
previous_replicas:
type: integer
description: The previous instance count
previous_parameters:
type: object
additionalProperties: true
description: The previous parameters
started_at:
type: string
description: When the change started
nullable: true
completed_at:
type: string
description: When the change completed
nullable: true
created_at:
type: string
description: When the change request was created
updated_at:
type: string
description: When the change request was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
replica:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- state
- cluster_name
- cluster_display_name
- cluster_rank
- replicas
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_rank
- previous_replicas
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- replica
required:
- type
- current_page
- per_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}/read-only-replicas:
get:
tags:
- Read-only replicas
operationId: list_read_only_replicas
summary: List read-only replicas
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
responses:
"200":
description: Returns read-only replicas
headers: {}
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the read-only replica
name:
type: string
description: The name of the read-only replica
state:
type: string
description: "The state of the read-only replica: pending, ready, or deleting"
replicas:
type: integer
description: The number of instances serving reads in this read-only replica
cluster_name:
type: string
description: The SKU representing the cluster size of the read-only replica
cluster_display_name:
type: string
description: The SKU representing the cluster size of the read-only replica, for display
access_host_url:
type: string
description: The database connection host for the read-only replica
private_access_host_url:
type: string
description: The private database connection host for the read-only replica
private_connection_service_name:
type: string
description: The service name to set up private connectivity for the read-only replica
nullable: true
created_at:
type: string
description: When the read-only replica was created
updated_at:
type: string
description: When the read-only replica was last updated
ready_at:
type: string
description: When the read-only replica was ready to serve queries
nullable: true
ready:
type: boolean
description: Whether or not the read-only replica is ready to serve queries
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgconf
description: The namespace of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- integer
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter, which is the primary's current value
disabled_reason:
type: string
description: Why the parameter cannot be changed
nullable: true
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
nullable: true
updated_at:
type: string
description: When the parameter was last updated
nullable: true
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter, floored at the primary's current value
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
units:
items:
type: string
type: array
description: Display units for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- namespace
- name
- display_name
- category
- description
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- url
- options
- units
- actor
required:
- id
- name
- state
- replicas
- cluster_name
- cluster_display_name
- access_host_url
- private_access_host_url
- private_connection_service_name
- created_at
- updated_at
- ready_at
- ready
- actor
- region
- 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` |
post:
tags:
- Read-only replicas
operationId: create_read_only_replica
summary: Create a read-only replica
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The read-only replica name
region:
type: string
description: The region slug for the read-only replica
replicas:
type: integer
description: The number of instances serving reads. Defaults to 1.
cluster_size:
type: string
description: The cluster size SKU name. Defaults to the primary cluster size.
required:
- name
- region
responses:
"200":
description: Returns the new read-only replica
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the read-only replica
name:
type: string
description: The name of the read-only replica
state:
type: string
description: "The state of the read-only replica: pending, ready, or deleting"
replicas:
type: integer
description: The number of instances serving reads in this read-only replica
cluster_name:
type: string
description: The SKU representing the cluster size of the read-only replica
cluster_display_name:
type: string
description: The SKU representing the cluster size of the read-only replica, for display
access_host_url:
type: string
description: The database connection host for the read-only replica
private_access_host_url:
type: string
description: The private database connection host for the read-only replica
private_connection_service_name:
type: string
description: The service name to set up private connectivity for the read-only replica
nullable: true
created_at:
type: string
description: When the read-only replica was created
updated_at:
type: string
description: When the read-only replica was last updated
ready_at:
type: string
description: When the read-only replica was ready to serve queries
nullable: true
ready:
type: boolean
description: Whether or not the read-only replica is ready to serve queries
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgconf
description: The namespace of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- integer
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter, which is the primary's current value
disabled_reason:
type: string
description: Why the parameter cannot be changed
nullable: true
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
nullable: true
updated_at:
type: string
description: When the parameter was last updated
nullable: true
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter, floored at the primary's current value
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
units:
items:
type: string
type: array
description: Display units for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- namespace
- name
- display_name
- category
- description
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- url
- options
- units
- actor
required:
- id
- name
- state
- replicas
- cluster_name
- cluster_display_name
- access_host_url
- private_access_host_url
- private_connection_service_name
- created_at
- updated_at
- ready_at
- ready
- actor
- region
- 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}/read-only-replicas/{id}:
patch:
tags:
- Read-only replicas
operationId: update_read_only_replica
summary: Update a read-only replica
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the read-only replica
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
replicas:
type: integer
description: The number of instances serving reads
cluster_size:
type: string
description: The cluster size SKU name
parameters:
type: object
additionalProperties: true
description: "Configuration parameters nested by namespace (e.g., {\"pgconf\": {\"max_connections\": \"300\"}}). Values must be greater than or equal to the primary's."
responses:
"200":
description: Returns the updated read-only replica
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the read-only replica
name:
type: string
description: The name of the read-only replica
state:
type: string
description: "The state of the read-only replica: pending, ready, or deleting"
replicas:
type: integer
description: The number of instances serving reads in this read-only replica
cluster_name:
type: string
description: The SKU representing the cluster size of the read-only replica
cluster_display_name:
type: string
description: The SKU representing the cluster size of the read-only replica, for display
access_host_url:
type: string
description: The database connection host for the read-only replica
private_access_host_url:
type: string
description: The private database connection host for the read-only replica
private_connection_service_name:
type: string
description: The service name to set up private connectivity for the read-only replica
nullable: true
created_at:
type: string
description: When the read-only replica was created
updated_at:
type: string
description: When the read-only replica was last updated
ready_at:
type: string
description: When the read-only replica was ready to serve queries
nullable: true
ready:
type: boolean
description: Whether or not the read-only replica is ready to serve queries
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgconf
description: The namespace of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- integer
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter, which is the primary's current value
disabled_reason:
type: string
description: Why the parameter cannot be changed
nullable: true
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
nullable: true
updated_at:
type: string
description: When the parameter was last updated
nullable: true
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter, floored at the primary's current value
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
units:
items:
type: string
type: array
description: Display units for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- namespace
- name
- display_name
- category
- description
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- url
- options
- units
- actor
required:
- id
- name
- state
- replicas
- cluster_name
- cluster_display_name
- access_host_url
- private_access_host_url
- private_connection_service_name
- created_at
- updated_at
- ready_at
- ready
- actor
- region
- 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` |
delete:
tags:
- Read-only replicas
operationId: delete_read_only_replica
summary: Delete a read-only replica
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the read-only replica
schema:
type: string
responses:
"204":
description: Deletes the read-only replica
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}/resizes:
delete:
tags:
- Branch changes
operationId: cancel_branch_change_request
summary: Cancel a change request
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
responses:
"204":
description: Cancels a change request
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
get:
tags:
- api-branch_resizes
operationId: list_branch_resize_requests
summary: Get branch resize requests
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns branch resize requests
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the branch resize request
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
- queued
description: The state of the branch resize request
started_at:
type: string
description: When the branch resize request started
nullable: true
completed_at:
type: string
description: When the branch resize request completed
nullable: true
created_at:
type: string
description: When the branch resize request was created
updated_at:
type: string
description: When the branch resize request was last updated
vtgate_size:
type: string
description: The size of the vtgate cluster
previous_vtgate_size:
type: string
description: The previous size of the vtgate cluster
vtgate_count:
type: integer
description: The number of vtgates in an availability zone
previous_vtgate_count:
type: integer
description: The previous number of vtgates in the availability zone
vtgate_max_count:
type: integer
description: The maximum number of vtgates in an availability zone when autoscaling is enabled
previous_vtgate_max_count:
type: integer
description: The previous maximum number of vtgates in the availability zone when autoscaling is enabled
vtgate_autoscaling:
type: boolean
description: If autoscaling is enabled for the vtgate cluster
previous_vtgate_autoscaling:
type: boolean
description: The previous autoscaling setting for the vtgate cluster
vtgate_target_cpu_utilization:
type: number
description: The target CPU utilization for the vtgate cluster
previous_vtgate_target_cpu_utilization:
type: number
description: The previous target CPU utilization for the vtgate cluster
vtgate_name:
type: string
description: "The SKU representing the vtgate cluster size: VTG_5, VTG_10,…"
vtgate_display_name:
type: string
description: The SKU representing the vtgate cluster size for display
previous_vtgate_name:
type: string
description: The previous SKU representing the vtgate cluster size
previous_vtgate_display_name:
type: string
description: The previous SKU representing the vtgate cluster size for display
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- vtgate_size
- previous_vtgate_size
- vtgate_count
- previous_vtgate_count
- vtgate_max_count
- previous_vtgate_max_count
- vtgate_autoscaling
- previous_vtgate_autoscaling
- vtgate_target_cpu_utilization
- previous_vtgate_target_cpu_utilization
- vtgate_name
- vtgate_display_name
- previous_vtgate_name
- previous_vtgate_display_name
- actor
required:
- type
- current_page
- per_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` |
put:
tags:
- api-branch_resizes
operationId: update_branch_resize_request
summary: Upsert a resize request
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:
vtgate_size:
type: string
description: "The size of the vtgate cluster: VTG_5, VTG_10,…"
vtgate_count:
type: integer
description: The number of vtgates in an availability zone
vtgate_max_count:
type: integer
description: The maximum number of vtgates in an availability zone when autoscaling is enabled
vtgate_autoscaling:
type: boolean
description: If autoscaling is enabled for the vtgate cluster
vtgate_target_cpu_utilization:
type: integer
description: The target CPU utilization for the vtgate cluster when autoscaling is enabled
responses:
"200":
description: Returns branch resize request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch resize request
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
- queued
description: The state of the branch resize request
started_at:
type: string
description: When the branch resize request started
nullable: true
completed_at:
type: string
description: When the branch resize request completed
nullable: true
created_at:
type: string
description: When the branch resize request was created
updated_at:
type: string
description: When the branch resize request was last updated
vtgate_size:
type: string
description: The size of the vtgate cluster
previous_vtgate_size:
type: string
description: The previous size of the vtgate cluster
vtgate_count:
type: integer
description: The number of vtgates in an availability zone
previous_vtgate_count:
type: integer
description: The previous number of vtgates in the availability zone
vtgate_max_count:
type: integer
description: The maximum number of vtgates in an availability zone when autoscaling is enabled
previous_vtgate_max_count:
type: integer
description: The previous maximum number of vtgates in the availability zone when autoscaling is enabled
vtgate_autoscaling:
type: boolean
description: If autoscaling is enabled for the vtgate cluster
previous_vtgate_autoscaling:
type: boolean
description: The previous autoscaling setting for the vtgate cluster
vtgate_target_cpu_utilization:
type: number
description: The target CPU utilization for the vtgate cluster
previous_vtgate_target_cpu_utilization:
type: number
description: The previous target CPU utilization for the vtgate cluster
vtgate_name:
type: string
description: "The SKU representing the vtgate cluster size: VTG_5, VTG_10,…"
vtgate_display_name:
type: string
description: The SKU representing the vtgate cluster size for display
previous_vtgate_name:
type: string
description: The previous SKU representing the vtgate cluster size
previous_vtgate_display_name:
type: string
description: The previous SKU representing the vtgate cluster size for display
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- vtgate_size
- previous_vtgate_size
- vtgate_count
- previous_vtgate_count
- vtgate_max_count
- previous_vtgate_max_count
- vtgate_autoscaling
- previous_vtgate_autoscaling
- vtgate_target_cpu_utilization
- previous_vtgate_target_cpu_utilization
- vtgate_name
- vtgate_display_name
- previous_vtgate_name
- previous_vtgate_display_name
- actor
"204":
description: No changes to apply
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/resizes/{resize}:
get:
tags:
- api-branch_resizes
operationId: get_branch_resize_request
summary: Get a branch resize request
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: resize
in: path
required: true
description: The ID of the branch resize request
schema:
type: string
responses:
"200":
description: Returns a branch resize request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch resize request
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
- queued
description: The state of the branch resize request
started_at:
type: string
description: When the branch resize request started
nullable: true
completed_at:
type: string
description: When the branch resize request completed
nullable: true
created_at:
type: string
description: When the branch resize request was created
updated_at:
type: string
description: When the branch resize request was last updated
vtgate_size:
type: string
description: The size of the vtgate cluster
previous_vtgate_size:
type: string
description: The previous size of the vtgate cluster
vtgate_count:
type: integer
description: The number of vtgates in an availability zone
previous_vtgate_count:
type: integer
description: The previous number of vtgates in the availability zone
vtgate_max_count:
type: integer
description: The maximum number of vtgates in an availability zone when autoscaling is enabled
previous_vtgate_max_count:
type: integer
description: The previous maximum number of vtgates in the availability zone when autoscaling is enabled
vtgate_autoscaling:
type: boolean
description: If autoscaling is enabled for the vtgate cluster
previous_vtgate_autoscaling:
type: boolean
description: The previous autoscaling setting for the vtgate cluster
vtgate_target_cpu_utilization:
type: number
description: The target CPU utilization for the vtgate cluster
previous_vtgate_target_cpu_utilization:
type: number
description: The previous target CPU utilization for the vtgate cluster
vtgate_name:
type: string
description: "The SKU representing the vtgate cluster size: VTG_5, VTG_10,…"
vtgate_display_name:
type: string
description: The SKU representing the vtgate cluster size for display
previous_vtgate_name:
type: string
description: The previous SKU representing the vtgate cluster size
previous_vtgate_display_name:
type: string
description: The previous SKU representing the vtgate cluster size for display
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- vtgate_size
- previous_vtgate_size
- vtgate_count
- previous_vtgate_count
- vtgate_max_count
- previous_vtgate_max_count
- vtgate_autoscaling
- previous_vtgate_autoscaling
- vtgate_target_cpu_utilization
- previous_vtgate_target_cpu_utilization
- vtgate_name
- vtgate_display_name
- previous_vtgate_name
- previous_vtgate_display_name
- 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}/roles:
get:
tags:
- Roles
operationId: list_roles
summary: List roles
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
- name: status
in: query
description: Filter roles by status
schema:
type: string
- name: q
in: query
description: Search roles by name or username
schema:
type: string
responses:
"200":
description: Returns roles
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plaintext password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
ready:
type: boolean
description: Whether the role is ready to accept connections
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- 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
with_replication:
type: boolean
description: Whether the role has the REPLICATION attribute
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- ready
- expired
- default
- ttl
- inherited_roles
- with_replication
- branch
- actor
- query_safety_settings
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
post:
tags:
- Roles
operationId: create_role
summary: Create role credentials
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the role
ttl:
type: integer
description: Time to live in seconds
inherited_roles:
type: array
items:
type: string
enum:
- 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
with_replication:
type: boolean
description: Whether the role should have the REPLICATION attribute
require_where_on_delete:
type: string
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
description: Require WHERE clause on UPDATE statements
responses:
"200":
description: Returns the new credentials
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plaintext password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
ready:
type: boolean
description: Whether the role is ready to accept connections
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- 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
with_replication:
type: boolean
description: Whether the role has the REPLICATION attribute
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- ready
- expired
- default
- ttl
- inherited_roles
- with_replication
- branch
- actor
- query_safety_settings
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`create_production_branch_password`, `create_production_read_only_branch_password`, `create_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/default:
get:
tags:
- Roles
operationId: get_default_role
summary: Get the default postgres role
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
responses:
"200":
description: Returns the default postgres role
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plaintext password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
ready:
type: boolean
description: Whether the role is ready to accept connections
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- 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
with_replication:
type: boolean
description: Whether the role has the REPLICATION attribute
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- ready
- expired
- default
- ttl
- inherited_roles
- with_replication
- branch
- actor
- query_safety_settings
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/reset-default:
post:
tags:
- Roles
operationId: reset_default_role
summary: Reset default credentials
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
responses:
"200":
description: Returns the new credentials
headers: {}
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: The database user name
password:
type: string
description: The plaintext password
access_host_url:
type: string
description: The database connection host
required:
- username
- password
- access_host_url
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`delete_production_branch_password`, `delete_production_read_only_branch_password`, `delete_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/{id}:
get:
tags:
- Roles
operationId: get_role
summary: Get a role
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
- name: replica
in: query
description: Return connection details for a replica
schema:
type: boolean
- name: read_only_replica
in: query
description: Return connection details for this read-only replica
schema:
type: string
- name: bouncer
in: query
description: Return connection details for this bouncer
schema:
type: string
responses:
"200":
description: Returns a role
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plaintext password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
ready:
type: boolean
description: Whether the role is ready to accept connections
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- 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
with_replication:
type: boolean
description: Whether the role has the REPLICATION attribute
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- ready
- expired
- default
- ttl
- inherited_roles
- with_replication
- branch
- actor
- query_safety_settings
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
patch:
tags:
- Roles
operationId: update_role
summary: Update role name
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The new name of the role
require_where_on_delete:
type: string
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
description: Require WHERE clause on UPDATE statements
responses:
"200":
description: Returns the updated role
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plaintext password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
ready:
type: boolean
description: Whether the role is ready to accept connections
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- 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
with_replication:
type: boolean
description: Whether the role has the REPLICATION attribute
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- ready
- expired
- default
- ttl
- inherited_roles
- with_replication
- branch
- actor
- query_safety_settings
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`create_production_branch_password`, `create_production_read_only_branch_password`, `create_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
delete:
tags:
- Roles
operationId: delete_role
summary: Delete role credentials
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
- name: successor
in: query
description: The optional role to reassign ownership to before dropping. Accepts the role's ID, or its username with or without the branch ID suffix.
schema:
type: string
responses:
"204":
description: Deletes the role credentials
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`delete_production_branch_password`, `delete_production_read_only_branch_password`, `delete_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/{id}/reassign:
post:
tags:
- Roles
operationId: reassign_role_objects
summary: Reassign objects owned by one role to another role
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
successor:
type: string
description: The role to reassign ownership to. Accepts the role's ID, or its username with or without the branch ID suffix.
required:
- successor
responses:
"204":
description: Objects reassigned successfully
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`delete_production_branch_password`, `delete_production_read_only_branch_password`, `delete_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/{id}/renew:
post:
tags:
- Roles
operationId: renew_role
summary: Renew role expiration
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
responses:
"200":
description: Returns the renewed role
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plaintext password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
ready:
type: boolean
description: Whether the role is ready to accept connections
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- 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
with_replication:
type: boolean
description: Whether the role has the REPLICATION attribute
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- ready
- expired
- default
- ttl
- inherited_roles
- with_replication
- branch
- actor
- query_safety_settings
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`create_production_branch_password`, `create_production_read_only_branch_password`, `create_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/{id}/reset:
post:
tags:
- Roles
operationId: reset_role
summary: Reset a role's password
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
responses:
"200":
description: Returns the role with new password
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plaintext password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
ready:
type: boolean
description: Whether the role is ready to accept connections
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- 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
with_replication:
type: boolean
description: Whether the role has the REPLICATION attribute
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- ready
- expired
- default
- ttl
- inherited_roles
- with_replication
- branch
- actor
- query_safety_settings
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`delete_production_branch_password`, `delete_production_read_only_branch_password`, `delete_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/safe-migrations:
post:
tags:
- Database branches
operationId: enable_safe_migrations
summary: Enable safe migrations for a branch
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
"200":
description: Returns the branch with safe migrations enabled
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
nullable: true
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
nullable: true
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_name:
type: string
description: The public SKU representing the VTGate size
nullable: true
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
vtgate_autoscaling:
type: boolean
description: Whether VTGate autoscaling is enabled
vtgate_max_count:
type: integer
description: The maximum number of VTGate instances when autoscaling is enabled
nullable: true
vtgate_target_cpu_utilization:
type: integer
description: The target CPU utilization for VTGate autoscaling
nullable: true
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
nullable: true
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the branch
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
keyspace_count:
type: integer
description: The number of keyspaces in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
nullable: true
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_name
- vtgate_count
- vtgate_autoscaling
- vtgate_max_count
- vtgate_target_cpu_utilization
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- deletion_protected
- sharded
- shard_count
- keyspace_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
put:
tags:
- Database branches
operationId: update_safe_migrations
summary: Update safe migrations for a branch
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
safe_migrations:
type: boolean
description: Whether safe migrations are enabled
required:
- safe_migrations
responses:
"200":
description: Returns the branch with safe migrations updated
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
nullable: true
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
nullable: true
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_name:
type: string
description: The public SKU representing the VTGate size
nullable: true
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
vtgate_autoscaling:
type: boolean
description: Whether VTGate autoscaling is enabled
vtgate_max_count:
type: integer
description: The maximum number of VTGate instances when autoscaling is enabled
nullable: true
vtgate_target_cpu_utilization:
type: integer
description: The target CPU utilization for VTGate autoscaling
nullable: true
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
nullable: true
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the branch
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
keyspace_count:
type: integer
description: The number of keyspaces in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
nullable: true
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_name
- vtgate_count
- vtgate_autoscaling
- vtgate_max_count
- vtgate_target_cpu_utilization
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- deletion_protected
- sharded
- shard_count
- keyspace_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
delete:
tags:
- Database branches
operationId: disable_safe_migrations
summary: Disable safe migrations for a branch
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
"200":
description: Returns the branch with safe migrations disabled
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
nullable: true
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
nullable: true
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_name:
type: string
description: The public SKU representing the VTGate size
nullable: true
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
vtgate_autoscaling:
type: boolean
description: Whether VTGate autoscaling is enabled
vtgate_max_count:
type: integer
description: The maximum number of VTGate instances when autoscaling is enabled
nullable: true
vtgate_target_cpu_utilization:
type: integer
description: The target CPU utilization for VTGate autoscaling
nullable: true
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
nullable: true
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the branch
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
keyspace_count:
type: integer
description: The number of keyspaces in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
nullable: true
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_name
- vtgate_count
- vtgate_autoscaling
- vtgate_max_count
- vtgate_target_cpu_utilization
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- deletion_protected
- sharded
- shard_count
- keyspace_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/branches/{branch}/schema:
get:
tags:
- Database branches
operationId: get_branch_schema
summary: Get a branch schema
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: query
description: Return the schema for a single Vitess keyspace
schema:
type: string
- name: namespace
in: query
description: Return the schema for a PostgreSQL catalog namespace in `.` format (e.g. public.schema1)
schema:
type: string
responses:
"200":
description: Gets the schema for the branch
headers: {}
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
name:
type: string
description: Name of the table
html:
type: string
description: Syntax highlighted HTML for the table's schema
raw:
type: string
description: The table's schema
required:
- name
- html
- raw
required:
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/schema/lint:
get:
tags:
- Database branches
operationId: lint_branch_schema
summary: Lint a branch schema
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns a list of schema errors for a branch
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
lint_error:
type: string
description: Code representing the type of error
subject_type:
type: string
enum:
- table
- vschema
- routing_rules
description: The subject for the errors
keyspace_name:
type: string
description: The keyspace of the schema with the error
table_name:
type: string
description: The table with the error
error_description:
type: string
description: A description for the error that occurred
docs_url:
type: string
description: A link to the documentation related to the error
column_name:
type: string
description: The column in a table relevant to the error
foreign_key_column_names:
items:
type: string
type: array
description: A list of invalid foreign key columns in a table
auto_increment_column_names:
items:
type: string
type: array
description: A list of invalid auto-incremented columns
charset_name:
type: string
description: The charset of the schema
engine_name:
type: string
description: The engine of the schema
vindex_name:
type: string
description: The name of the vindex for the schema
json_path:
type: string
description: The path for an invalid JSON column
check_constraint_name:
type: string
description: The name of the invalid check constraint
enum_value:
type: string
description: The name of the invalid enum value
partitioning_type:
type: string
description: The name of the invalid partitioning type
partition_name:
type: string
description: The name of the invalid partition in the schema
required:
- lint_error
- subject_type
- keyspace_name
- table_name
- error_description
- docs_url
- column_name
- foreign_key_column_names
- auto_increment_column_names
- charset_name
- engine_name
- vindex_name
- json_path
- check_constraint_name
- enum_value
- partitioning_type
- partition_name
required:
- type
- current_page
- per_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}/switchovers:
get:
tags:
- Switchovers
operationId: list_switchovers
summary: List switchovers
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns switchovers
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the switchover
state:
type: string
enum:
- pending
- running
- succeeded
- failed
- canceled
description: The state of the switchover
method:
type: string
enum:
- switchover
- restart
description: How the primary was moved. `switchover` promotes a replica on a highly available branch; `restart` restarts the single instance of a branch that has no replicas. Absent until the operator selects one.
nullable: true
error:
type: string
description: Why the switchover failed. A failed switchover has an unconfirmed outcome and does not imply the primary stayed put.
nullable: true
started_at:
type: string
description: When the switchover was requested
nullable: true
completed_at:
type: string
description: When the switchover finished
nullable: true
created_at:
type: string
description: When the switchover was created
updated_at:
type: string
description: When the switchover was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
required:
- type
- current_page
- per_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:
- Switchovers
operationId: create_switchover
summary: Create a switchover
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
candidate:
type: string
description: The exact `name` of the replica returned by the branch's Postgres infrastructure endpoint to promote. Omit to let the operator select an eligible replica. Only applies to branches with replicas.
responses:
"201":
description: Returns the new switchover
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the switchover
state:
type: string
enum:
- pending
- running
- succeeded
- failed
- canceled
description: The state of the switchover
method:
type: string
enum:
- switchover
- restart
description: How the primary was moved. `switchover` promotes a replica on a highly available branch; `restart` restarts the single instance of a branch that has no replicas. Absent until the operator selects one.
nullable: true
error:
type: string
description: Why the switchover failed. A failed switchover has an unconfirmed outcome and does not imply the primary stayed put.
nullable: true
started_at:
type: string
description: When the switchover was requested
nullable: true
completed_at:
type: string
description: When the switchover finished
nullable: true
created_at:
type: string
description: When the switchover was created
updated_at:
type: string
description: When the switchover was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
"400":
description: "bad request: candidate must be a string"
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: "unprocessable: the branch cannot accept a switchover right now"
"500":
description: Internal Server Error
description: |2-
Moves the primary of a Postgres branch.
On a branch with replicas the primary steps down and a replica is
promoted in its place. A branch running a single instance has nothing to
promote, so that instance is restarted where it stands and the branch is
unreachable while it comes back. Read `method` on the response to see
which one the branch got.
A branch accepts one switchover at a time. A switchover that ends in the
`failed` state has an unconfirmed outcome: the primary may still have
moved, and nothing is rolled back.
### 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}/switchovers/{id}:
get:
tags:
- Switchovers
operationId: get_switchover
summary: Get a switchover
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the switchover
schema:
type: string
responses:
"200":
description: Returns a switchover
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the switchover
state:
type: string
enum:
- pending
- running
- succeeded
- failed
- canceled
description: The state of the switchover
method:
type: string
enum:
- switchover
- restart
description: How the primary was moved. `switchover` promotes a replica on a highly available branch; `restart` restarts the single instance of a branch that has no replicas. Absent until the operator selects one.
nullable: true
error:
type: string
description: Why the switchover failed. A failed switchover has an unconfirmed outcome and does not imply the primary stayed put.
nullable: true
started_at:
type: string
description: When the switchover was requested
nullable: true
completed_at:
type: string
description: When the switchover finished
nullable: true
created_at:
type: string
description: When the switchover was created
updated_at:
type: string
description: When the switchover was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- 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}/traffic/budgets:
get:
tags:
- Traffic budgets
operationId: list_traffic_budgets
summary: List traffic budgets
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
- name: period
in: query
description: Time period filter
schema:
type: string
enum:
- 15m
- 1h
- 3h
- 6h
- 12h
- 1d
- 2d
- 7d
- 8d
- name: created_at
in: query
description: "Filter by creation date range (format: 'start..end')"
schema:
type: string
- name: fingerprint
in: query
description: Filter budgets by query fingerprint
schema:
type: string
responses:
"200":
description: Returns the traffic budgets for the branch
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic budget
name:
type: string
description: The name of the budget
mode:
type: string
enum:
- enforce
- warn
- off
description: The mode of the budget
capacity:
type: number
description: The maximum capacity that can be banked, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
rate:
type: number
description: The rate at which capacity refills, as a percentage of server resources (0-100). Unlimited when not set.
nullable: true
burst:
type: number
description: The maximum capacity a single query can consume, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
concurrency:
type: number
description: The percentage of available worker processes this policy can use (0-100). Unlimited when not set.
nullable: true
warning_threshold:
type: number
description: A percentage of capacity, burst, or concurrency thresholds to emit warnings for enforced budgets (0-100).
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
rules:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
- each
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
created_at:
type: string
description: When the budget was created
updated_at:
type: string
description: When the budget was updated
required:
- id
- name
- mode
- actor
- rules
- created_at
- updated_at
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
post:
tags:
- Traffic budgets
operationId: create_traffic_budget
summary: Create a traffic budget
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the traffic budget
mode:
type: string
enum:
- enforce
- warn
- off
description: The mode of the traffic budget
capacity:
type: integer
description: The maximum capacity that can be banked, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
rate:
type: integer
description: The rate at which capacity refills, as a percentage of server resources (0-100). Unlimited when not set.
burst:
type: integer
description: The maximum capacity a single query can consume, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
concurrency:
type: integer
description: The percentage of available worker processes this policy can use (0-100). Unlimited when not set.
warning_threshold:
type: integer
description: A percentage of capacity, burst, or concurrency thresholds to emit warnings for enforced budgets (0-100).
rules:
type: array
items:
type: string
description: Array of traffic rules to apply to the budget
responses:
"201":
description: Returns the created traffic budget
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the traffic budget
name:
type: string
description: The name of the budget
mode:
type: string
enum:
- enforce
- warn
- off
description: The mode of the budget
capacity:
type: number
description: The maximum capacity that can be banked, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
rate:
type: number
description: The rate at which capacity refills, as a percentage of server resources (0-100). Unlimited when not set.
nullable: true
burst:
type: number
description: The maximum capacity a single query can consume, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
concurrency:
type: number
description: The percentage of available worker processes this policy can use (0-100). Unlimited when not set.
nullable: true
warning_threshold:
type: number
description: A percentage of capacity, burst, or concurrency thresholds to emit warnings for enforced budgets (0-100).
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
rules:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
- each
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
created_at:
type: string
description: When the budget was created
updated_at:
type: string
description: When the budget was updated
required:
- id
- name
- mode
- actor
- rules
- created_at
- updated_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/traffic/budgets/{budget_id}/rules:
post:
tags:
- Traffic rules
operationId: create_traffic_rule
summary: Create a traffic rule
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: budget_id
in: path
required: true
description: The ID of the traffic budget
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
kind:
type: string
enum:
- match
- each
description: Kind of rule
keyspace:
type: string
description: The keyspace to apply a query pattern rule to
fingerprint:
type: string
description: Query pattern fingerprint to apply rule to
tags:
type: array
items:
type: string
description: Optional array of tags for this rule. Each rules take exactly one tag.
responses:
"201":
description: Returns the created traffic rule
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
- each
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/traffic/budgets/{budget_id}/rules/{id}:
delete:
tags:
- Traffic rules
operationId: delete_traffic_rule
summary: Delete a traffic rule
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: budget_id
in: path
required: true
description: The ID of the traffic budget
schema:
type: string
- name: id
in: path
required: true
description: The ID of the traffic rule
schema:
type: string
responses:
"204":
description: Traffic rule successfully deleted
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/traffic/budgets/{id}:
get:
tags:
- Traffic budgets
operationId: get_traffic_budget
summary: Get a traffic budget
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the traffic budget
schema:
type: string
responses:
"200":
description: Returns the traffic budget
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the traffic budget
name:
type: string
description: The name of the budget
mode:
type: string
enum:
- enforce
- warn
- off
description: The mode of the budget
capacity:
type: number
description: The maximum capacity that can be banked, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
rate:
type: number
description: The rate at which capacity refills, as a percentage of server resources (0-100). Unlimited when not set.
nullable: true
burst:
type: number
description: The maximum capacity a single query can consume, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
concurrency:
type: number
description: The percentage of available worker processes this policy can use (0-100). Unlimited when not set.
nullable: true
warning_threshold:
type: number
description: A percentage of capacity, burst, or concurrency thresholds to emit warnings for enforced budgets (0-100).
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
rules:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
- each
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
created_at:
type: string
description: When the budget was created
updated_at:
type: string
description: When the budget was updated
required:
- id
- name
- mode
- actor
- rules
- created_at
- updated_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
patch:
tags:
- Traffic budgets
operationId: update_traffic_budget
summary: Update a traffic budget
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the traffic budget
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the traffic budget
mode:
type: string
enum:
- enforce
- warn
- off
description: The mode of the traffic budget
capacity:
type: integer
description: The maximum capacity that can be banked, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
rate:
type: integer
description: The rate at which capacity refills, as a percentage of server resources (0-100). Unlimited when not set.
burst:
type: integer
description: The maximum capacity a single query can consume, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
concurrency:
type: integer
description: The percentage of available worker processes this policy can use (0-100). Unlimited when not set.
warning_threshold:
type: integer
description: A percentage of capacity, burst, or concurrency thresholds to emit warnings for enforced budgets (0-100).
rules:
type: array
items:
type: string
description: Array of traffic rules to apply to the budget
responses:
"200":
description: Returns the updated traffic budget
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the traffic budget
name:
type: string
description: The name of the budget
mode:
type: string
enum:
- enforce
- warn
- off
description: The mode of the budget
capacity:
type: number
description: The maximum capacity that can be banked, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
rate:
type: number
description: The rate at which capacity refills, as a percentage of server resources (0-100). Unlimited when not set.
nullable: true
burst:
type: number
description: The maximum capacity a single query can consume, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
concurrency:
type: number
description: The percentage of available worker processes this policy can use (0-100). Unlimited when not set.
nullable: true
warning_threshold:
type: number
description: A percentage of capacity, burst, or concurrency thresholds to emit warnings for enforced budgets (0-100).
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
rules:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
- each
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
created_at:
type: string
description: When the budget was created
updated_at:
type: string
description: When the budget was updated
required:
- id
- name
- mode
- actor
- rules
- created_at
- updated_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
delete:
tags:
- Traffic budgets
operationId: delete_traffic_budget
summary: Delete a traffic budget
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the traffic budget
schema:
type: string
responses:
"204":
description: Traffic budget successfully deleted
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/cidrs:
get:
tags:
- Database Postgres IP restrictions
operationId: list_database_postgres_cidrs
summary: List IP restriction entries
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns IP restriction entries for the database
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
description:
type: string
description: An optional description for the IP restriction rule
nullable: true
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- schema
- role
- cidrs
- description
- created_at
- updated_at
- deleted_at
- actor
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Invalid parameters or validation errors
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`, `read_databases`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
post:
tags:
- Database Postgres IP restrictions
operationId: create_database_postgres_cidr
summary: Create an IP restriction entry
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
schema:
type: string
description: The PostgreSQL schema to restrict access to. Leave empty or omit to allow access to all schemas.
role:
type: string
description: The PostgreSQL role to restrict access to. Leave empty or omit to allow access for all roles.
cidrs:
type: array
items:
type: string
description: List of IPv4 CIDR ranges (e.g., ['192.168.1.0/24', '192.168.1.1/32']). Must contain at least one valid IPv4 address or range.
description:
type: string
description: An optional description for the IP restriction rule.
required:
- cidrs
responses:
"201":
description: Returns the created IP restriction entry
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
description:
type: string
description: An optional description for the IP restriction rule
nullable: true
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- schema
- role
- cidrs
- description
- created_at
- updated_at
- deleted_at
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Invalid parameters or validation errors
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/cidrs/{id}:
get:
tags:
- Database Postgres IP restrictions
operationId: get_database_postgres_cidr
summary: Get an IP restriction entry
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the IP restriction entry
schema:
type: string
responses:
"200":
description: Returns an IP restriction entry
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
description:
type: string
description: An optional description for the IP restriction rule
nullable: true
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- schema
- role
- cidrs
- description
- created_at
- updated_at
- deleted_at
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Invalid parameters or validation errors
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`, `read_databases`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
patch:
tags:
- Database Postgres IP restrictions
operationId: update_database_postgres_cidr
summary: Update an IP restriction entry
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the IP restriction entry
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
schema:
type: string
description: The PostgreSQL schema to restrict access to. Leave empty to allow access to all schemas.
role:
type: string
description: The PostgreSQL role to restrict access to. Leave empty to allow access for all roles.
cidrs:
type: array
items:
type: string
description: List of IPv4 CIDR ranges (e.g., ['192.168.1.0/24', '192.168.1.1/32']). Only provided fields will be updated.
description:
type: string
description: An optional description for the IP restriction rule. Pass an empty string to clear.
responses:
"200":
description: Returns the updated IP restriction entry
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
description:
type: string
description: An optional description for the IP restriction rule
nullable: true
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- schema
- role
- cidrs
- description
- created_at
- updated_at
- deleted_at
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Invalid parameters or validation errors
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
delete:
tags:
- Database Postgres IP restrictions
operationId: delete_database_postgres_cidr
summary: Delete an IP restriction entry
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the IP restriction entry
schema:
type: string
responses:
"204":
description: "IP restriction entry deleted successfully. Note: This will also remove the restriction from all database branches."
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Invalid parameters or validation errors
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/deploy-queue:
get:
tags:
- Deploy requests
operationId: get_deploy_queue
summary: Get the deploy queue
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns the deploy queue for a database
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |
The deploy queue returns the current list of deploy requests in the order they will be deployed.
/organizations/{organization}/databases/{database}/deploy-requests:
get:
tags:
- Deploy requests
operationId: list_deploy_requests
summary: List deploy requests
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: state
in: query
description: Filter by state of the deploy request (open, closed, deployed)
schema:
type: string
- name: branch
in: query
description: Filter by the name of the branch the deploy request is created from
schema:
type: string
- name: into_branch
in: query
description: Filter by the name of the branch the deploy request will be merged into
schema:
type: string
- name: deployed_at
in: query
description: Filter deploy requests by the date they were deployed. (e.g. 2023-01-01T00:00:00Z..2023-01-31T23:59:59Z)
schema:
type: string
- name: running_at
in: query
description: Filter deploy requests by the date they were running. (e.g. 2023-01-01T00:00:00Z..2023-01-31T23:59:59Z)
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns a list of deploy requests
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
List deploy requests for a database
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
post:
tags:
- Deploy requests
operationId: create_deploy_request
summary: Create a deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
branch:
type: string
description: The name of the branch the deploy request is created from
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
notes:
type: string
description: Notes about the deploy request
auto_cutover:
type: boolean
description: Whether or not to enable auto_cutover for the deploy request. When enabled, will auto cutover to the new schema as soon as it is ready.
auto_delete_branch:
type: boolean
description: Whether or not to enable auto_delete_branch for the deploy request. When enabled, will delete the branch once the DR successfully completes.
required:
- branch
- into_branch
responses:
"201":
description: Returns the created deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_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**
`create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_deploy_requests` |
| Database | `write_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}:
get:
tags:
- Deploy requests
operationId: get_deploy_request
summary: Get a deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
"200":
description: Returns information about a deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
patch:
tags:
- Deploy requests
operationId: close_deploy_request
summary: Close a deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
state:
type: string
enum:
- closed
description: The deploy request will be updated to this state
responses:
"200":
description: Returns the updated deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_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**
`create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_deploy_requests` |
| Database | `write_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/apply-deploy:
post:
tags:
- Deploy requests
operationId: complete_gated_deploy_request
summary: Complete a gated deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
"200":
description: Returns the deploy request whose deployment has been completed
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_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**
`create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/auto-apply:
put:
tags:
- Deploy requests
operationId: update_auto_apply
summary: Update auto-apply for deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
enable:
type: boolean
description: Whether or not to enable auto-apply for the deploy request
responses:
"200":
description: Returns the deploy request whose auto-apply setting was updated
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Enables or disabled the auto-apply setting for a deploy request
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/auto-delete-branch:
put:
tags:
- Deploy requests
operationId: update_auto_delete_branch
summary: Update auto-delete branch for deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
enable:
type: boolean
description: Whether or not to enable auto-delete branch for the deploy request
responses:
"200":
description: Returns the deploy request whose auto-delete branch setting was updated
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Enables or disabled the auto-delete branch setting for a deploy request
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/cancel:
post:
tags:
- Deploy requests
operationId: cancel_deploy_request
summary: Cancel a queued deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
"200":
description: Returns the deploy request whose deployment was canceled
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_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**
`create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/complete-deploy:
post:
tags:
- Deploy requests
operationId: complete_errored_deploy
summary: Complete an errored deploy
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
"200":
description: Returns the completed deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_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**
`create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/deploy:
post:
tags:
- Deploy requests
operationId: queue_deploy_request
summary: Queue a deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
instant_ddl:
type: boolean
description: Whether or not to deploy the request with instant DDL. Defaults to false.
responses:
"200":
description: Returns the deployed deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_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**
`create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/deployment:
get:
tags:
- Deploy requests
operationId: get_deployment
summary: Get a deployment
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
"200":
description: Returns the deployment for a deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Get the deployment for a deploy request
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/force-cutover:
post:
tags:
- Deploy requests
operationId: force_cutover_deploy_request
summary: Enable force cutover for a deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
"200":
description: Returns the deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_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**
`create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/operations:
get:
tags:
- Deploy requests
operationId: list_deploy_operations
summary: List deploy operations
parameters:
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns deploy operations for the deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
List deploy operations for a deploy request
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/revert:
post:
tags:
- Deploy requests
operationId: complete_revert
summary: Complete a revert
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
"200":
description: Returns the deploy request that was reverted
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_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**
`create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/reviews:
get:
tags:
- Deploy requests
operationId: list_deploy_request_reviews
summary: List deploy request reviews
parameters:
- name: organization
in: path
required: true
description: The name of the organization the deploy request belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the deploy request belongs to
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns an array of deploy request reviews
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the review
body:
type: string
description: The text body of the review
html_body:
type: string
description: The HTML body of the review
state:
type: string
enum:
- commented
- approved
description: Whether the review is a comment or approval
created_at:
type: string
description: When the review was created
updated_at:
type: string
description: When the review was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- body
- html_body
- state
- created_at
- updated_at
- actor
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
post:
tags:
- Deploy requests
operationId: review_deploy_request
summary: Review a deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the organization the deploy request belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the deploy request belongs to
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
state:
type: string
enum:
- commented
- approved
description: Whether the review is a comment or approval. Service tokens must have corresponding access (either `approve_deploy_request` or `review_deploy_request`)
body:
type: string
description: Deploy request review comments
responses:
"201":
description: Returns the created deploy request review
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the review
body:
type: string
description: The text body of the review
html_body:
type: string
description: The HTML body of the review
state:
type: string
enum:
- commented
- approved
description: Whether the review is a comment or approval
created_at:
type: string
description: When the review was created
updated_at:
type: string
description: When the review was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- body
- html_body
- state
- created_at
- updated_at
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Review a deploy request by either approving or commenting on the deploy request
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`approve_deploy_request`, `review_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `approve_deploy_requests` |
| Database | `approve_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/skip-revert:
post:
tags:
- Deploy requests
operationId: skip_revert_period
summary: Skip revert period
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
"200":
description: Returns the deploy request whose deploy revert was skipped
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Skips the revert period for a deploy request
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/storage-check:
get:
tags:
- Deploy requests
operationId: check_deploy_request_storage
summary: Check deploy request storage
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
"200":
description: Returns storage check information for the deploy request
headers: {}
content:
application/json:
schema:
type: object
properties:
enough_storage:
type: boolean
description: Whether the cluster has enough storage to safely deploy
upgradeable:
type: boolean
description: Whether the target branch cluster can be upgraded for more storage
storage_bytes_needed:
type: integer
description: Total estimated bytes of additional storage needed for the deployment
storage_report:
type: object
additionalProperties:
type: object
description: Per-shard storage details. Keys are shard names.
additionalProperties:
type: object
properties:
used:
type: integer
description: Current storage used in bytes
capacity:
type: integer
description: Total storage capacity in bytes
remaining:
type: integer
description: Remaining storage available in bytes
percentage_used:
type: number
description: Percentage of storage capacity currently used
storage_needed:
type: integer
description: Estimated additional storage needed for this deployment in bytes
has_enough:
type: boolean
description: Whether this shard has enough remaining storage for the deployment
description: Per-keyspace and per-shard storage report. Keys are keyspace names.
required:
- enough_storage
- upgradeable
- storage_bytes_needed
- storage_report
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Checks whether the deploy request's target branch cluster has enough storage to safely deploy the schema changes.
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/throttler:
get:
tags:
- Deploy requests
operationId: get_deploy_request_throttler
summary: Get deploy request throttler configurations
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
"200":
description: Deploy request throttler configurations
headers: {}
content:
application/json:
schema:
type: object
properties:
keyspaces:
items:
type: string
type: array
description: Keyspaces that are eligible for throttler configuration in the configurable resource (database or deploy request)
configurable:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: A throttler ratio between 0 and 95 that applies to migrations in this specific keyspace
required:
- keyspace_name
- ratio
required:
- keyspaces
- configurable
- configurations
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
patch:
tags:
- Deploy requests
operationId: update_deploy_request_throttler
summary: Update deploy request throttler configurations
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
ratio:
type: integer
description: A throttler ratio between 0 and 95 that will apply to all keyspaces affected by the deploy request. 0 effectively disables throttler, while 95 drastically slows down migrations in the deploy request
configurations:
type: array
items:
type: string
description: 'If specifying throttler ratios per keyspace, an array of { "keyspace_name": "mykeyspace", "ratio": 10 }, one for each eligible keyspace'
responses:
"200":
description: Deploy request throttler configurations
headers: {}
content:
application/json:
schema:
type: object
properties:
keyspaces:
items:
type: string
type: array
description: Keyspaces that are eligible for throttler configuration in the configurable resource (database or deploy request)
configurable:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: A throttler ratio between 0 and 95 that applies to migrations in this specific keyspace
required:
- keyspace_name
- ratio
required:
- keyspaces
- configurable
- configurations
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/maintenance-schedules:
get:
tags:
- MaintenanceSchedules
operationId: list_maintenance_schedules
summary: List maintenance schedules
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns maintenance schedules for the database
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the maintenance schedule
name:
type: string
description: The display name of the maintenance schedule
created_at:
type: string
description: When the maintenance schedule was created
updated_at:
type: string
description: When the maintenance schedule was last updated
last_window_datetime:
type: string
description: When the last maintenance window started
next_window_datetime:
type: string
description: When the next maintenance window is scheduled
duration:
type: integer
description: The duration of the maintenance window in hours
day:
type: integer
description: Day of the week (0 = Sunday, 6 = Saturday, 7 = every day)
hour:
type: integer
description: Hour of the day in UTC (0-23)
week:
type: integer
description: Week of the month for monthly schedules (0-3)
frequency_value:
type: integer
description: The frequency value of the maintenance schedule
frequency_unit:
type: string
enum:
- day
- week
- month
- once
description: The frequency unit of the maintenance schedule
enabled:
type: boolean
description: Whether the maintenance schedule is enabled
expires_at:
type: string
description: When a one-time maintenance schedule expires
nullable: true
deadline_at:
type: string
description: The deadline for a required maintenance schedule
nullable: true
required:
type: boolean
description: Whether the maintenance schedule is required
pending_vitess_version_update:
type: boolean
description: Whether there is a pending Vitess version update
pending_vitess_version:
type: string
description: The pending Vitess version, if any
nullable: true
pending_mysql_version_update:
type: boolean
description: Whether there is a pending MySQL version update
pending_mysql_version:
type: string
description: The pending MySQL version, if any
nullable: true
required:
- id
- name
- created_at
- updated_at
- last_window_datetime
- next_window_datetime
- duration
- day
- hour
- week
- frequency_value
- frequency_unit
- enabled
- expires_at
- deadline_at
- required
- pending_vitess_version_update
- pending_vitess_version
- pending_mysql_version_update
- pending_mysql_version
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/maintenance-schedules/{id}:
get:
tags:
- MaintenanceSchedules
operationId: get_maintenance_schedule
summary: Get a maintenance schedule
parameters:
- name: id
in: path
required: true
description: The ID of the maintenance schedule
schema:
type: string
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
responses:
"200":
description: Returns a maintenance schedule
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the maintenance schedule
name:
type: string
description: The display name of the maintenance schedule
created_at:
type: string
description: When the maintenance schedule was created
updated_at:
type: string
description: When the maintenance schedule was last updated
last_window_datetime:
type: string
description: When the last maintenance window started
next_window_datetime:
type: string
description: When the next maintenance window is scheduled
duration:
type: integer
description: The duration of the maintenance window in hours
day:
type: integer
description: Day of the week (0 = Sunday, 6 = Saturday, 7 = every day)
hour:
type: integer
description: Hour of the day in UTC (0-23)
week:
type: integer
description: Week of the month for monthly schedules (0-3)
frequency_value:
type: integer
description: The frequency value of the maintenance schedule
frequency_unit:
type: string
enum:
- day
- week
- month
- once
description: The frequency unit of the maintenance schedule
enabled:
type: boolean
description: Whether the maintenance schedule is enabled
expires_at:
type: string
description: When a one-time maintenance schedule expires
nullable: true
deadline_at:
type: string
description: The deadline for a required maintenance schedule
nullable: true
required:
type: boolean
description: Whether the maintenance schedule is required
pending_vitess_version_update:
type: boolean
description: Whether there is a pending Vitess version update
pending_vitess_version:
type: string
description: The pending Vitess version, if any
nullable: true
pending_mysql_version_update:
type: boolean
description: Whether there is a pending MySQL version update
pending_mysql_version:
type: string
description: The pending MySQL version, if any
nullable: true
required:
- id
- name
- created_at
- updated_at
- last_window_datetime
- next_window_datetime
- duration
- day
- hour
- week
- frequency_value
- frequency_unit
- enabled
- expires_at
- deadline_at
- required
- pending_vitess_version_update
- pending_vitess_version
- pending_mysql_version_update
- pending_mysql_version
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/maintenance-schedules/{id}/windows:
get:
tags:
- MaintenanceWindows
operationId: list_maintenance_windows
summary: List maintenance windows
parameters:
- name: id
in: path
required: true
description: The ID of the maintenance schedule
schema:
type: string
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns maintenance windows for the schedule
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the maintenance window
created_at:
type: string
description: When the maintenance window was created
updated_at:
type: string
description: When the maintenance window was last updated
started_at:
type: string
description: When the maintenance window started
nullable: true
finished_at:
type: string
description: When the maintenance window finished
nullable: true
required:
- id
- created_at
- updated_at
- started_at
- finished_at
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/read-only-regions:
get:
tags:
- Databases
operationId: list_read_only_regions
summary: List read-only regions
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: List of the database's read-only regions
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the read-only region
display_name:
type: string
description: The name of the read-only region
created_at:
type: string
description: When the read-only region was created
updated_at:
type: string
description: When the read-only region was last updated
ready_at:
type: string
description: When the read-only region was ready to serve queries
nullable: true
ready:
type: boolean
description: Whether or not the read-only region is ready to serve queries
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
required:
- id
- display_name
- created_at
- updated_at
- ready_at
- ready
- actor
- region
required:
- type
- current_page
- per_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`, `promote_branches`, `demote_branches`, `delete_production_branch`, `connect_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `delete_branch_password`, `delete_production_branch_password`, `delete_production_read_only_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_comment`, `create_comment`, `restore_backup`, `restore_production_branch_backup`, `read_backups`, `write_backups`, `delete_backups`, `delete_production_branch_backups`, `write_branch_vschema`, `write_production_branch_vschema`, `read_workflow`, `write_workflow`, `delete_workflow`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
/organizations/{organization}/databases/{database}/regions:
get:
tags:
- Databases
operationId: list_database_regions
summary: List database regions
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns the available regions for a database
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
required:
- type
- current_page
- per_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`, `promote_branches`, `demote_branches`, `delete_production_branch`, `connect_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `delete_branch_password`, `delete_production_branch_password`, `delete_production_read_only_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_comment`, `create_comment`, `restore_backup`, `restore_production_branch_backup`, `read_backups`, `write_backups`, `delete_backups`, `delete_production_branch_backups`, `write_branch_vschema`, `write_production_branch_vschema`, `read_workflow`, `write_workflow`, `delete_workflow`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/schema-recommendations:
get:
tags:
- Schema recommendations
operationId: list_schema_recommendations
summary: List schema recommendations
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: state
in: query
description: Filter by recommendation state
schema:
type: string
enum:
- open
- closed
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns schema recommendations
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the schema recommendation
html_url:
type: string
description: The URL to the schema recommendation in the app
title:
type: string
description: The title of the schema recommendation
table_name:
type: string
description: The name of the table the recommendation applies to
keyspace:
type: string
description: The keyspace the recommendation applies to
ddl_statement:
type: string
description: The DDL statement to apply the recommendation
number:
type: integer
description: The number of the schema recommendation
state:
type: string
enum:
- open
- applied
- dismissed
- stale
description: The state of the recommendation
recommendation_type:
type: string
enum:
- unused_table
- unused_index
- duplicate_index
- sequence_overflow
- sequence_overflow_foreign_key
- new_index
- encoding_upgrade
- bloated_table
- bloated_index
description: The type of recommendation
created_at:
type: string
description: When the recommendation was created
updated_at:
type: string
description: When the recommendation was last updated
applied_at:
type: string
description: When the recommendation was applied
nullable: true
dismissed_at:
type: string
description: When the recommendation was dismissed
nullable: true
closed_by_deploy_request:
type: object
properties:
id:
type: string
description: The ID of the deploy request
branch_id:
type: string
description: The ID of the branch
number:
type: integer
description: The number of the deploy request
required:
- id
- branch_id
- number
nullable: true
dismissed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
required:
- id
- html_url
- title
- table_name
- keyspace
- ddl_statement
- number
- state
- recommendation_type
- created_at
- updated_at
- applied_at
- dismissed_at
- closed_by_deploy_request
- dismissed_by
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/schema-recommendations/{number}:
get:
tags:
- Schema recommendations
operationId: get_schema_recommendation
summary: Get a schema recommendation
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: number
in: path
required: true
description: "Schema recommendation sequence number. Example: `42`."
schema:
type: integer
responses:
"200":
description: Returns a schema recommendation
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the schema recommendation
html_url:
type: string
description: The URL to the schema recommendation in the app
title:
type: string
description: The title of the schema recommendation
table_name:
type: string
description: The name of the table the recommendation applies to
keyspace:
type: string
description: The keyspace the recommendation applies to
ddl_statement:
type: string
description: The DDL statement to apply the recommendation
number:
type: integer
description: The number of the schema recommendation
state:
type: string
enum:
- open
- applied
- dismissed
- stale
description: The state of the recommendation
recommendation_type:
type: string
enum:
- unused_table
- unused_index
- duplicate_index
- sequence_overflow
- sequence_overflow_foreign_key
- new_index
- encoding_upgrade
- bloated_table
- bloated_index
description: The type of recommendation
created_at:
type: string
description: When the recommendation was created
updated_at:
type: string
description: When the recommendation was last updated
applied_at:
type: string
description: When the recommendation was applied
nullable: true
dismissed_at:
type: string
description: When the recommendation was dismissed
nullable: true
closed_by_deploy_request:
type: object
properties:
id:
type: string
description: The ID of the deploy request
branch_id:
type: string
description: The ID of the branch
number:
type: integer
description: The number of the deploy request
required:
- id
- branch_id
- number
nullable: true
dismissed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
required:
- id
- html_url
- title
- table_name
- keyspace
- ddl_statement
- number
- state
- recommendation_type
- created_at
- updated_at
- applied_at
- dismissed_at
- closed_by_deploy_request
- dismissed_by
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/schema-recommendations/{number}/dismiss:
post:
tags:
- Schema recommendations
operationId: dismiss_schema_recommendation
summary: Dismiss a schema recommendation
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: number
in: path
required: true
description: "Schema recommendation sequence number. Example: `42`."
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: The reason for dismissing the recommendation (max 500 characters)
responses:
"200":
description: Returns the dismissed schema recommendation
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the schema recommendation
html_url:
type: string
description: The URL to the schema recommendation in the app
title:
type: string
description: The title of the schema recommendation
table_name:
type: string
description: The name of the table the recommendation applies to
keyspace:
type: string
description: The keyspace the recommendation applies to
ddl_statement:
type: string
description: The DDL statement to apply the recommendation
number:
type: integer
description: The number of the schema recommendation
state:
type: string
enum:
- open
- applied
- dismissed
- stale
description: The state of the recommendation
recommendation_type:
type: string
enum:
- unused_table
- unused_index
- duplicate_index
- sequence_overflow
- sequence_overflow_foreign_key
- new_index
- encoding_upgrade
- bloated_table
- bloated_index
description: The type of recommendation
created_at:
type: string
description: When the recommendation was created
updated_at:
type: string
description: When the recommendation was last updated
applied_at:
type: string
description: When the recommendation was applied
nullable: true
dismissed_at:
type: string
description: When the recommendation was dismissed
nullable: true
closed_by_deploy_request:
type: object
properties:
id:
type: string
description: The ID of the deploy request
branch_id:
type: string
description: The ID of the branch
number:
type: integer
description: The number of the deploy request
required:
- id
- branch_id
- number
nullable: true
dismissed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
required:
- id
- html_url
- title
- table_name
- keyspace
- ddl_statement
- number
- state
- recommendation_type
- created_at
- updated_at
- applied_at
- dismissed_at
- closed_by_deploy_request
- dismissed_by
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/throttler:
get:
tags:
- Databases
operationId: get_database_throttler
summary: Get database throttler configurations
parameters:
- name: organization
in: path
required: true
description: The name of the organization that the throttled deploy requests belong to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that the throttled deploy requests belong to
schema:
type: string
responses:
"200":
description: Database throttler configurations
headers: {}
content:
application/json:
schema:
type: object
properties:
keyspaces:
items:
type: string
type: array
description: Keyspaces that are eligible for throttler configuration in the configurable resource (database or deploy request)
configurable:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: A throttler ratio between 0 and 95 that applies to migrations in this specific keyspace
required:
- keyspace_name
- ratio
required:
- keyspaces
- configurable
- configurations
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
patch:
tags:
- Databases
operationId: update_database_throttler
summary: Update database throttler configurations
parameters:
- name: organization
in: path
required: true
description: The name of the organization that the throttled deploy requests belong to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database that the throttled deploy requests belong to
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
ratio:
type: integer
description: A throttler ratio between 0 and 95 that will apply to all keyspaces in the database. 0 effectively disables throttler, while 95 drastically slows down deploy request migrations
configurations:
type: array
items:
type: string
description: 'If specifying throttler ratios per keyspace, an array of { "keyspace_name": "mykeyspace", "ratio": 10 }, one for each eligible keyspace'
responses:
"200":
description: Database throttler configurations
headers: {}
content:
application/json:
schema:
type: object
properties:
keyspaces:
items:
type: string
type: array
description: Keyspaces that are eligible for throttler configuration in the configurable resource (database or deploy request)
configurable:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: A throttler ratio between 0 and 95 that applies to migrations in this specific keyspace
required:
- keyspace_name
- ratio
required:
- keyspaces
- configurable
- configurations
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/webhooks:
get:
tags:
- Webhooks
operationId: list_webhooks
summary: List webhooks
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns a list of webhooks for a database
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
nullable: true
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- backup.failed
- backup.succeeded
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
List webhooks for a database
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
post:
tags:
- Webhooks
operationId: create_webhook
summary: Create a webhook
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
url:
type: string
description: The URL the webhook will send events to
enabled:
type: boolean
description: Whether the webhook should be enabled
events:
type: array
items:
type: string
description: The events this webhook should subscribe to
required:
- url
responses:
"201":
description: Returns the created webhook
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
nullable: true
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- backup.failed
- backup.succeeded
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/webhooks/{id}:
get:
tags:
- Webhooks
operationId: get_webhook
summary: Get a webhook
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the webhook
schema:
type: string
responses:
"200":
description: Returns the webhook
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
nullable: true
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- backup.failed
- backup.succeeded
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
patch:
tags:
- Webhooks
operationId: update_webhook
summary: Update a webhook
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the webhook
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
url:
type: string
description: The URL the webhook will send events to
enabled:
type: boolean
description: Whether the webhook should be enabled
events:
type: array
items:
type: string
description: The events this webhook should subscribe to
responses:
"200":
description: Returns the updated webhook
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
nullable: true
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- backup.failed
- backup.succeeded
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
delete:
tags:
- Webhooks
operationId: delete_webhook
summary: Delete a webhook
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the webhook
schema:
type: string
responses:
"204":
description: Webhook successfully deleted
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/webhooks/{id}/test:
post:
tags:
- Webhooks
operationId: test_webhook
summary: Test a webhook
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the webhook
schema:
type: string
responses:
"204":
description: Webhook test event successfully triggered
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Sends a test event to the webhook
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/workflows:
get:
tags:
- Workflows
operationId: list_workflows
summary: List workflows
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: between
in: query
description: Filter workflows to those active during a time range (e.g. 2025-01-01T00:00:00Z..2025-01-01T23:59:59)
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns workflows
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
post:
tags:
- Workflows
operationId: create_workflow
summary: Create a workflow
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name the workflow
source_keyspace:
type: string
description: Name of the source keyspace
target_keyspace:
type: string
description: Name of the target keyspace
global_keyspace:
type: string
description: Name of the global sequence keyspace
defer_secondary_keys:
type: boolean
description: Defer secondary keys
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
tables:
type: array
items:
type: string
description: List of tables to move
required:
- name
- source_keyspace
- target_keyspace
- tables
responses:
"201":
description: Returns the workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}:
get:
tags:
- Workflows
operationId: get_workflow
summary: Get a workflow
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
delete:
tags:
- Workflows
operationId: workflow_cancel
summary: Cancel a workflow
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/complete:
patch:
tags:
- Workflows
operationId: workflow_complete
summary: Complete a workflow
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/cutover:
patch:
tags:
- Workflows
operationId: workflow_cutover
summary: Cutover traffic
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/retry:
patch:
tags:
- Workflows
operationId: workflow_retry
summary: Retry a failed workflow
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/reverse-cutover:
patch:
tags:
- Workflows
operationId: workflow_reverse_cutover
summary: Reverse traffic cutover
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/reverse-traffic:
patch:
tags:
- Workflows
operationId: workflow_reverse_traffic
summary: Reverse traffic
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/switch-primaries:
patch:
tags:
- Workflows
operationId: workflow_switch_primaries
summary: Switch primary traffic
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/switch-replicas:
patch:
tags:
- Workflows
operationId: workflow_switch_replicas
summary: Switch replica traffic
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/verify-data:
patch:
tags:
- Workflows
operationId: verify_workflow
summary: Verify workflow data
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: integer
responses:
"200":
description: Returns a workflow
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/invoices:
get:
tags:
- Invoices
operationId: list_invoices
summary: Get invoices
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Gets the invoices for an organization
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the invoice
total:
type: string
description: The total amount of the invoice, as a stringified decimal to preserve precision
billing_period_start:
type: string
description: Start of the billing period
billing_period_end:
type: string
description: End of the billing period
paid:
type: boolean
description: Whether the invoice has been paid
overdue:
type: boolean
description: Whether the invoice is past due and unpaid
required:
- id
- total
- billing_period_start
- billing_period_end
- paid
- overdue
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Get the invoices for an organization
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_invoices`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_invoices` |
/organizations/{organization}/invoices/{id}:
get:
tags:
- Invoices
operationId: get_invoice
summary: Get an invoice
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: id
in: path
required: true
description: "Invoice public ID from `list_invoices`. Example: `aabb12123434`."
schema:
type: string
responses:
"200":
description: Returns an invoice
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the invoice
total:
type: string
description: The total amount of the invoice, as a stringified decimal to preserve precision
billing_period_start:
type: string
description: Start of the billing period
billing_period_end:
type: string
description: End of the billing period
paid:
type: boolean
description: Whether the invoice has been paid
overdue:
type: boolean
description: Whether the invoice is past due and unpaid
required:
- id
- total
- billing_period_start
- billing_period_end
- paid
- overdue
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_invoices`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_invoices` |
/organizations/{organization}/invoices/{id}/line-items:
get:
tags:
- Invoices
operationId: get_invoice_line_items
summary: Get invoice line items
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: id
in: path
required: true
description: "Invoice public ID from `list_invoices`. Example: `aabb12123434`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Gets the line items for an invoice
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the line item
subtotal:
type: number
description: The total for the line item
description:
type: string
description: The description for the line item
metric_name:
type: string
description: The name of the billable item
cloudflare_billed:
type: boolean
description: Whether the line item is billed through Cloudflare
database_id:
type: string
description: The ID for the billed database
database_name:
type: string
description: The name for the billed database
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- subtotal
- description
- metric_name
- cloudflare_billed
- database_id
- database_name
- resource
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Get the line items for an invoice
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_invoices`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_invoices` |
/organizations/{organization}/members:
get:
tags:
- Organization members
operationId: list_organization_members
summary: List organization members
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: q
in: query
description: Search term to filter members by name or email
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns members of the organization
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
required:
- id
- user
- role
- created_at
- updated_at
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_organization` |
/organizations/{organization}/members/{id}:
get:
tags:
- Organization members
operationId: get_organization_membership
summary: Get an organization member
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: id
in: path
required: true
description: The ID of the user
schema:
type: string
responses:
"200":
description: Returns the membership of the user in the organization
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
required:
- id
- user
- role
- created_at
- updated_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_organization` |
patch:
tags:
- Organization members
operationId: update_organization_membership
summary: Update organization member role
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: id
in: path
required: true
description: The ID of the user
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
role:
type: string
description: "The role to assign to the member (e.g., 'admin', 'member'). Note: Cannot update your own role. Roles managed by IdP cannot be updated via API."
required:
- role
responses:
"200":
description: Returns the updated membership
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
required:
- id
- user
- role
- created_at
- updated_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
delete:
tags:
- Organization members
operationId: remove_organization_member
summary: Remove a member from an organization
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: id
in: path
required: true
description: The ID of the user
schema:
type: string
- name: delete_passwords
in: query
description: Whether to delete all passwords associated with the member. Only available when removing other members (not yourself).
schema:
type: boolean
- name: delete_service_tokens
in: query
description: Whether to delete all service tokens associated with the member. Only available when removing other members (not yourself).
schema:
type: boolean
responses:
"204":
description: "Member removed successfully. Note: Cannot remove the last admin or leave your only organization."
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
/organizations/{organization}/oauth-applications:
get:
tags:
- OAuth applications
operationId: list_oauth_applications
summary: List OAuth applications
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth applications belong to
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns a list of the organization's oauth applications
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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:
type: string
description: The scopes that the OAuth application requires on a user account, as a space-separated string
avatar:
type: string
description: The image source for the OAuth application's avatar
client_id:
type: string
description: The OAuth application's unique client id
tokens:
type: integer
description: The number of tokens issued by the OAuth application
dcr:
type: boolean
description: Whether the OAuth application was created via Dynamic Client Registration
single_org_authorization:
type: boolean
description: Whether the OAuth application is limited to authorizing a single organization
requires_org_scope:
type: boolean
description: Whether the OAuth application requires at least one organization to be authorized
scopes_by_resource:
type: object
additionalProperties: true
description: Scopes grouped by resource type (database, organization, branch, user) with scope, description, and admin flag
all_scopes_by_resource:
type: object
additionalProperties: true
description: All available scopes grouped by resource type with scope, description, selected, and admin flags
mcp_tool_groups:
items:
type: object
additionalProperties: true
type: array
description: MCP tool groups (id, label, section, tools, scopes, parent_id, default_enabled, roles) selectable when authorizing a DCR app; only present for DCR apps. Database-section groups also carry org_scopes (the organization-tier scope names granting the group across all databases in an organization) and org_roles (the organization roles allowed to grant them); both are null for organization-section groups
nullable: true
required:
- id
- name
- redirect_uri
- domain
- created_at
- updated_at
- scopes
- avatar
- client_id
- tokens
- dcr
- single_org_authorization
- requires_org_scope
- scopes_by_resource
- all_scopes_by_resource
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_oauth_applications`
/organizations/{organization}/oauth-applications/{application_id}:
get:
tags:
- OAuth applications
operationId: get_oauth_application
summary: Get an OAuth application
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth application belongs to
schema:
type: string
- name: application_id
in: path
required: true
description: The ID of the OAuth application
schema:
type: string
responses:
"200":
description: Returns information abuot an OAuth application
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the app
name:
type: string
description: The name of the app
redirect_uri:
type: string
description: The redirect URI of the OAuth application
domain:
type: string
description: The domain of the OAuth application. Used for verification of a valid redirect uri
created_at:
type: string
description: When the OAuth application was created
updated_at:
type: string
description: When the OAuth application was last updated
scopes:
type: string
description: The scopes that the OAuth application requires on a user account, as a space-separated string
avatar:
type: string
description: The image source for the OAuth application's avatar
client_id:
type: string
description: The OAuth application's unique client id
tokens:
type: integer
description: The number of tokens issued by the OAuth application
dcr:
type: boolean
description: Whether the OAuth application was created via Dynamic Client Registration
single_org_authorization:
type: boolean
description: Whether the OAuth application is limited to authorizing a single organization
requires_org_scope:
type: boolean
description: Whether the OAuth application requires at least one organization to be authorized
scopes_by_resource:
type: object
additionalProperties: true
description: Scopes grouped by resource type (database, organization, branch, user) with scope, description, and admin flag
all_scopes_by_resource:
type: object
additionalProperties: true
description: All available scopes grouped by resource type with scope, description, selected, and admin flags
mcp_tool_groups:
items:
type: object
additionalProperties: true
type: array
description: MCP tool groups (id, label, section, tools, scopes, parent_id, default_enabled, roles) selectable when authorizing a DCR app; only present for DCR apps. Database-section groups also carry org_scopes (the organization-tier scope names granting the group across all databases in an organization) and org_roles (the organization roles allowed to grant them); both are null for organization-section groups
nullable: true
required:
- id
- name
- redirect_uri
- domain
- created_at
- updated_at
- scopes
- avatar
- client_id
- tokens
- dcr
- single_org_authorization
- requires_org_scope
- scopes_by_resource
- all_scopes_by_resource
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_oauth_applications`
/organizations/{organization}/oauth-applications/{application_id}/tokens:
get:
tags:
- OAuth applications
operationId: list_oauth_tokens
summary: List OAuth tokens
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth application belongs to
schema:
type: string
- name: application_id
in: path
required: true
description: The ID of the OAuth application
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns the OAuth tokens issued on behalf of the OAuth application
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
nullable: true
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
nullable: true
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
List OAuth tokens created by an OAuth application
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_oauth_tokens`
/organizations/{organization}/oauth-applications/{application_id}/tokens/{token_id}:
get:
tags:
- OAuth applications
operationId: get_oauth_token
summary: Get an OAuth token
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth application belongs to
schema:
type: string
- name: application_id
in: path
required: true
description: The ID of the OAuth application
schema:
type: string
- name: token_id
in: path
required: true
description: The ID of the OAuth application token
schema:
type: string
responses:
"200":
description: Returns an OAuth token that was issued on behalf of the OAuth application
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
nullable: true
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
nullable: true
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_oauth_tokens`
delete:
tags:
- OAuth applications
operationId: delete_oauth_token
summary: Delete an OAuth token
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth application belongs to
schema:
type: string
- name: application_id
in: path
required: true
description: The ID of the OAuth application
schema:
type: string
- name: token_id
in: path
required: true
description: The ID of the OAuth application token
schema:
type: string
responses:
"204":
description: Deletes an OAuth application's OAuth token
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`delete_oauth_tokens`
/organizations/{organization}/oauth-applications/{id}/token:
post:
tags:
- OAuth tokens
operationId: create_oauth_token
summary: Create or renew an OAuth token
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth application belongs to
schema:
type: string
- name: id
in: path
required: true
description: The ID of the OAuth application
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
client_id:
type: string
description: The OAuth application's client ID
client_secret:
type: string
description: The OAuth application's client secret
grant_type:
type: string
enum:
- authorization_code
- refresh_token
description: Whether an OAuth grant code or a refresh token is being exchanged for an OAuth token
code:
type: string
description: The OAuth grant code provided to your OAuth application's redirect URI. Required when grant_type is authorization_code
redirect_uri:
type: string
description: The OAuth application's redirect URI. Required when grant_type is authorization_code
refresh_token:
type: string
description: The refresh token from the original OAuth token grant. Required when grant_type is refresh_token
required:
- client_id
- client_secret
- grant_type
responses:
"200":
description: Returns the created OAuth token
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
nullable: true
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
nullable: true
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity
"500":
description: Internal Server Error
description: |+
Create an OAuth token from an authorization grant code, or refresh an OAuth token from a refresh token
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`write_oauth_tokens`
/organizations/{organization}/regions:
get:
tags:
- Organizations
operationId: list_regions_for_organization
summary: List regions for an organization
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns the organization's regions
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| User | `read_organizations` |
| Organization | `read_organization` |
/organizations/{organization}/service-tokens:
get:
tags:
- Service tokens
operationId: list_service_tokens
summary: List service tokens
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns the organization's service tokens
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
nullable: true
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
nullable: true
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
List service tokens for an organization.
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_service_tokens`
post:
tags:
- Service tokens
operationId: create_service_token
summary: Create a service token
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the service token
ttl:
type: integer
description: Time to live (in seconds) for the service token. The token will be invalid when TTL has passed
responses:
"200":
description: Returns the created service token with the plaintext token
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
nullable: true
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
nullable: true
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
Create a new service token for the organization.
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`write_service_tokens`
/organizations/{organization}/service-tokens/{id}:
get:
tags:
- Service tokens
operationId: get_service_token
summary: Get a service token
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: id
in: path
required: true
description: The ID of the service token
schema:
type: string
responses:
"200":
description: Returns the service token
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
nullable: true
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
nullable: true
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
Get information about a service token.
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_service_tokens`
delete:
tags:
- Service tokens
operationId: delete_service_token
summary: Delete a service token
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: id
in: path
required: true
description: The ID of the service token
schema:
type: string
responses:
"204":
description: Service token deleted successfully
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
Delete a service token from the organization.
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`delete_service_tokens`
/organizations/{organization}/sso:
get:
tags:
- Organization SSO
operationId: get_organization_sso
summary: Get organization SSO status
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
responses:
"200":
description: Returns organization SSO status
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- OrganizationSSO
description: The resource type
id:
type: string
description: The organization ID
enabled:
type: boolean
description: Whether the SSO add-on is enabled for the organization
configured:
type: boolean
description: Whether an identity provider connection is active
directory:
type: boolean
description: Whether directory sync is enabled
has_verified_domain:
type: boolean
description: Whether the organization has at least one verified email domain
domains:
type: array
items:
type: object
properties:
type:
type: string
enum:
- OrganizationDomain
description: The resource type
id:
type: string
description: The public ID of the organization domain
domain:
type: string
description: The domain name
state:
type: string
enum:
- pending
- verified
- failed
description: The verification state of the domain
verified_at:
type: string
description: When the domain was verified
nullable: true
failure_reason:
type: string
description: The reason domain verification failed
nullable: true
created_at:
type: string
description: When the domain was created
updated_at:
type: string
description: When the domain was last updated
required:
- type
- id
- domain
- state
- verified_at
- failure_reason
- created_at
- updated_at
domain_verification_url:
type: string
description: URL to open for verifying an email domain, returned when SSO is enabled
nullable: true
required:
- type
- id
- enabled
- configured
- directory
- has_verified_domain
- domains
- domain_verification_url
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Get SSO add-on status, identity provider connection state, directory sync, and verified domains
### 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**
`manage_sso`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_sso` |
post:
tags:
- Organization SSO
operationId: enable_organization_sso
summary: Enable organization SSO
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
responses:
"200":
description: Returns organization SSO status and a domain verification URL
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- OrganizationSSO
description: The resource type
id:
type: string
description: The organization ID
enabled:
type: boolean
description: Whether the SSO add-on is enabled for the organization
configured:
type: boolean
description: Whether an identity provider connection is active
directory:
type: boolean
description: Whether directory sync is enabled
has_verified_domain:
type: boolean
description: Whether the organization has at least one verified email domain
domains:
type: array
items:
type: object
properties:
type:
type: string
enum:
- OrganizationDomain
description: The resource type
id:
type: string
description: The public ID of the organization domain
domain:
type: string
description: The domain name
state:
type: string
enum:
- pending
- verified
- failed
description: The verification state of the domain
verified_at:
type: string
description: When the domain was verified
nullable: true
failure_reason:
type: string
description: The reason domain verification failed
nullable: true
created_at:
type: string
description: When the domain was created
updated_at:
type: string
description: When the domain was last updated
required:
- type
- id
- domain
- state
- verified_at
- failure_reason
- created_at
- updated_at
domain_verification_url:
type: string
description: URL to open for verifying an email domain, returned when SSO is enabled
nullable: true
required:
- type
- id
- enabled
- configured
- directory
- has_verified_domain
- domains
- domain_verification_url
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Enable the SSO add-on and return a URL for verifying an email domain
### 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**
`manage_sso`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_sso` |
delete:
tags:
- Organization SSO
operationId: disable_organization_sso
summary: Disable organization SSO
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
responses:
"200":
description: Returns organization SSO status after disabling SSO
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- OrganizationSSO
description: The resource type
id:
type: string
description: The organization ID
enabled:
type: boolean
description: Whether the SSO add-on is enabled for the organization
configured:
type: boolean
description: Whether an identity provider connection is active
directory:
type: boolean
description: Whether directory sync is enabled
has_verified_domain:
type: boolean
description: Whether the organization has at least one verified email domain
domains:
type: array
items:
type: object
properties:
type:
type: string
enum:
- OrganizationDomain
description: The resource type
id:
type: string
description: The public ID of the organization domain
domain:
type: string
description: The domain name
state:
type: string
enum:
- pending
- verified
- failed
description: The verification state of the domain
verified_at:
type: string
description: When the domain was verified
nullable: true
failure_reason:
type: string
description: The reason domain verification failed
nullable: true
created_at:
type: string
description: When the domain was created
updated_at:
type: string
description: When the domain was last updated
required:
- type
- id
- domain
- state
- verified_at
- failure_reason
- created_at
- updated_at
domain_verification_url:
type: string
description: URL to open for verifying an email domain, returned when SSO is enabled
nullable: true
required:
- type
- id
- enabled
- configured
- directory
- has_verified_domain
- domains
- domain_verification_url
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Disable SSO and directory sync for the 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**
`manage_sso`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_sso` |
/organizations/{organization}/sso/configure:
post:
tags:
- Organization SSO
operationId: configure_organization_sso
summary: Open the SSO configuration portal
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
responses:
"200":
description: Identity provider setup URL
headers: {}
content:
application/json:
schema:
type: object
properties:
portal_url:
type: string
description: URL to open for configuring the identity provider
required:
- portal_url
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Return a URL for configuring the identity provider. Requires at least one verified domain.
### 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**
`manage_sso`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_sso` |
/organizations/{organization}/sso/directory:
post:
tags:
- Organization SSO
operationId: enable_organization_sso_directory
summary: Open the directory sync portal
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
responses:
"200":
description: Directory sync setup URL
headers: {}
content:
application/json:
schema:
type: object
properties:
portal_url:
type: string
description: URL to open for configuring directory sync
required:
- portal_url
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Return a URL for configuring directory sync. Requires SSO to be enabled.
### 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**
`manage_sso`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_sso` |
delete:
tags:
- Organization SSO
operationId: disable_organization_sso_directory
summary: Disable directory sync
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
responses:
"200":
description: Returns organization SSO status after disabling directory sync
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- OrganizationSSO
description: The resource type
id:
type: string
description: The organization ID
enabled:
type: boolean
description: Whether the SSO add-on is enabled for the organization
configured:
type: boolean
description: Whether an identity provider connection is active
directory:
type: boolean
description: Whether directory sync is enabled
has_verified_domain:
type: boolean
description: Whether the organization has at least one verified email domain
domains:
type: array
items:
type: object
properties:
type:
type: string
enum:
- OrganizationDomain
description: The resource type
id:
type: string
description: The public ID of the organization domain
domain:
type: string
description: The domain name
state:
type: string
enum:
- pending
- verified
- failed
description: The verification state of the domain
verified_at:
type: string
description: When the domain was verified
nullable: true
failure_reason:
type: string
description: The reason domain verification failed
nullable: true
created_at:
type: string
description: When the domain was created
updated_at:
type: string
description: When the domain was last updated
required:
- type
- id
- domain
- state
- verified_at
- failure_reason
- created_at
- updated_at
domain_verification_url:
type: string
description: URL to open for verifying an email domain, returned when SSO is enabled
nullable: true
required:
- type
- id
- enabled
- configured
- directory
- has_verified_domain
- domains
- domain_verification_url
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Disable directory sync for the organization. Non-admin directory members are removed.
### 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**
`manage_sso`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_sso` |
/organizations/{organization}/sso/domains:
get:
tags:
- Organization SSO domains
operationId: list_organization_sso_domains
summary: List organization SSO domains
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
responses:
"200":
description: Returns SSO domains
headers: {}
content:
application/json:
schema:
type: array
items:
type: object
properties:
type:
type: string
enum:
- OrganizationDomain
description: The resource type
id:
type: string
description: The public ID of the organization domain
domain:
type: string
description: The domain name
state:
type: string
enum:
- pending
- verified
- failed
description: The verification state of the domain
verified_at:
type: string
description: When the domain was verified
nullable: true
failure_reason:
type: string
description: The reason domain verification failed
nullable: true
created_at:
type: string
description: When the domain was created
updated_at:
type: string
description: When the domain was last updated
required:
- type
- id
- domain
- state
- verified_at
- failure_reason
- created_at
- updated_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
List email domains registered for organization SSO
### 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**
`manage_sso`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_sso` |
post:
tags:
- Organization SSO domains
operationId: create_organization_sso_domain
summary: Start SSO domain verification
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
responses:
"200":
description: Domain verification URL
headers: {}
content:
application/json:
schema:
type: object
properties:
portal_url:
type: string
description: URL to open for verifying an email domain
required:
- portal_url
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Enable SSO if needed and return a URL for verifying an email domain
### 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**
`manage_sso`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_sso` |
/organizations/{organization}/sso/domains/{id}:
get:
tags:
- Organization SSO domains
operationId: get_organization_sso_domain
summary: Get an SSO domain
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: id
in: path
required: true
description: The public ID of the organization domain
schema:
type: string
responses:
"200":
description: Returns the SSO domain
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- OrganizationDomain
description: The resource type
id:
type: string
description: The public ID of the organization domain
domain:
type: string
description: The domain name
state:
type: string
enum:
- pending
- verified
- failed
description: The verification state of the domain
verified_at:
type: string
description: When the domain was verified
nullable: true
failure_reason:
type: string
description: The reason domain verification failed
nullable: true
created_at:
type: string
description: When the domain was created
updated_at:
type: string
description: When the domain was last updated
required:
- type
- id
- domain
- state
- verified_at
- failure_reason
- created_at
- updated_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Get a registered SSO email domain and its verification state
### 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**
`manage_sso`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_sso` |
delete:
tags:
- Organization SSO domains
operationId: delete_organization_sso_domain
summary: Delete an SSO domain
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: id
in: path
required: true
description: The public ID of the organization domain
schema:
type: string
responses:
"204":
description: The domain was deleted
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Delete a verified or pending SSO domain
### 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**
`manage_sso`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_sso` |
/organizations/{organization}/teams:
get:
tags:
- Organization teams
operationId: list_organization_teams
summary: List teams in an organization
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: q
in: query
description: Search term to filter teams by name
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns teams in the organization
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the team
display_name:
type: string
description: The display name of the team
creator:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
members:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
analyst_databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
name:
type: string
description: The name of the team
slug:
type: string
description: The slug of the team
created_at:
type: string
description: When the team was created
updated_at:
type: string
description: When the team was last updated
description:
type: string
description: The description of the team
nullable: true
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
required:
- id
- display_name
- creator
- members
- databases
- analyst_databases
- name
- slug
- created_at
- updated_at
- description
- managed
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
"400":
description: Bad Request - Invalid operation or parameters
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Validation errors or SSO-managed teams
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_organization` |
post:
tags:
- Organization teams
operationId: create_organization_team
summary: Create an organization team
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the team
description:
type: string
description: A description of the team's purpose
required:
- name
responses:
"200":
description: Returns the created team
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the team
display_name:
type: string
description: The display name of the team
creator:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
members:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
analyst_databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
name:
type: string
description: The name of the team
slug:
type: string
description: The slug of the team
created_at:
type: string
description: When the team was created
updated_at:
type: string
description: When the team was last updated
description:
type: string
description: The description of the team
nullable: true
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
required:
- id
- display_name
- creator
- members
- databases
- analyst_databases
- name
- slug
- created_at
- updated_at
- description
- managed
"400":
description: Bad Request - Invalid operation or parameters
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Validation errors or SSO-managed teams
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_teams`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
/organizations/{organization}/teams/{team}:
get:
tags:
- Organization teams
operationId: get_organization_team
summary: Get an organization team
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
responses:
"200":
description: Returns the team details including members and databases
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the team
display_name:
type: string
description: The display name of the team
creator:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
members:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
analyst_databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
name:
type: string
description: The name of the team
slug:
type: string
description: The slug of the team
created_at:
type: string
description: When the team was created
updated_at:
type: string
description: When the team was last updated
description:
type: string
description: The description of the team
nullable: true
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
required:
- id
- display_name
- creator
- members
- databases
- analyst_databases
- name
- slug
- created_at
- updated_at
- description
- managed
"400":
description: Bad Request - Invalid operation or parameters
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Validation errors or SSO-managed teams
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_organization` |
patch:
tags:
- Organization teams
operationId: update_organization_team
summary: Update an organization team
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The new name for the team
description:
type: string
description: The new description for the team
responses:
"200":
description: "Returns the updated team. Note: SSO-managed teams cannot be updated."
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the team
display_name:
type: string
description: The display name of the team
creator:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
members:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
analyst_databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
name:
type: string
description: The name of the team
slug:
type: string
description: The slug of the team
created_at:
type: string
description: When the team was created
updated_at:
type: string
description: When the team was last updated
description:
type: string
description: The description of the team
nullable: true
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
required:
- id
- display_name
- creator
- members
- databases
- analyst_databases
- name
- slug
- created_at
- updated_at
- description
- managed
"400":
description: Bad Request - Invalid operation or parameters
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Validation errors or SSO-managed teams
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_teams`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
delete:
tags:
- Organization teams
operationId: delete_organization_team
summary: Delete an organization team
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
responses:
"204":
description: "Team deleted successfully. Note: SSO-managed teams cannot be deleted."
headers: {}
"400":
description: Bad Request - Invalid operation or parameters
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Validation errors or SSO-managed teams
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_teams`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
/organizations/{organization}/teams/{team}/members:
get:
tags:
- Team members
operationId: list_organization_team_members
summary: List team members
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns the list of team members
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the team membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
passwords:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: The list of hosts in each availability zone providing direct access to a vtgate
ttl_seconds:
type: integer
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plaintext password. Null except in the response from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
required:
- id
- user
- actor
- created_at
- updated_at
- passwords
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
"400":
description: Bad Request - Invalid operation or SSO-managed team
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Validation errors
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_organization` |
post:
tags:
- Team members
operationId: add_organization_team_member
summary: Add a member to a team
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: The ID of the organization member to add to the team
required:
- user_id
responses:
"200":
description: Returns the created team membership
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the team membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
passwords:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: The list of hosts in each availability zone providing direct access to a vtgate
ttl_seconds:
type: integer
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plaintext password. Null except in the response from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
required:
- id
- user
- actor
- created_at
- updated_at
- passwords
"400":
description: Bad Request - Invalid operation or SSO-managed team
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Validation errors
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_teams`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
/organizations/{organization}/teams/{team}/members/{id}:
get:
tags:
- Team members
operationId: get_organization_team_member
summary: Get a team member
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
- name: id
in: path
required: true
description: The ID of the team membership or the ID of the member
schema:
type: string
responses:
"200":
description: Returns the team member details
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the team membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
passwords:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: The list of hosts in each availability zone providing direct access to a vtgate
ttl_seconds:
type: integer
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plaintext password. Null except in the response from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
required:
- id
- user
- actor
- created_at
- updated_at
- passwords
"400":
description: Bad Request - Invalid operation or SSO-managed team
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Validation errors
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_organization` |
delete:
tags:
- Team members
operationId: remove_organization_team_member
summary: Remove a member from a team
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
- name: id
in: path
required: true
description: The ID of the team membership or the ID of the member to remove
schema:
type: string
- name: delete_passwords
in: query
description: Whether to delete the member's passwords created through this team
schema:
type: boolean
responses:
"204":
description: "Member removed successfully. Note: SSO-managed teams cannot have members removed."
headers: {}
"400":
description: Bad Request - Invalid operation or SSO-managed team
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Validation errors
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_teams`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_organization` |
/regions:
get:
tags:
- Regions
operationId: list_public_regions
summary: List public regions
parameters:
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns the available public PlanetScale regions
headers: {}
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: The cloud provider for the region
enabled:
type: boolean
description: Whether new clusters can be created in this region
public_ip_addresses:
items:
type: string
type: array
description: List of public IP addresses for the region
display_name:
type: string
description: The name of the region
location:
type: string
description: The location of the region
slug:
type: string
description: The slug identifier for the region
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |
Endpoint is available without authentication.
/user:
get:
tags:
- Users
operationId: get_current_user
summary: Get current user
responses:
"200":
description: Returns the user associated with this service token
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Get the user associated with this service token
### Authorization
A OAuth token must have at least one of the following scopes in order to use this API endpoint:
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| User | `read_user` |
tags:
- name: BackupPolicies
description: |2
Resources for managing database backup policies.
- name: Backups
description: |2
Resources for managing database branch backups.
- name: Branch changes
description: |2
Resources for managing cluster changes.
- name: Branch config changes
description: |2
Resources for managing branch-level configuration change requests.
- name: Cluster extensions
description: |2
Resources for managing cluster extension configuration.
- name: Branch log signatures
description: |2
Resources for retrieving branch log access signatures.
- name: Cluster parameters
description: |2
Resources for managing cluster configuration parameters.
- name: Database branch keyspaces
description: |2
Resources for managing keyspaces.
- name: Database branch passwords
description: |2
Resources for managing database branch passwords.
- name: Database Postgres IP restrictions
description: |2
Resources for managing Postgres IP restriction entries for databases.
Note: This endpoint is only available for PostgreSQL databases. For MySQL databases, use the Database Branch Passwords endpoint.
- name: Databases
description: |2
Resources for managing databases within an organization.
- name: Keyspace config changes
description: |2
Resources for managing keyspace-level configuration change requests.
- name: Keyspace resizes
description: |2
Resources for managing keyspace resize requests.
- name: Keyspace VSchemas
description: |2
Resources for managing VSchemas within a keyspace.
- name: MaintenanceSchedules
description: |2
Resources for viewing database maintenance schedules for Vitess databases (Enterprise only).
- name: MaintenanceWindows
description: |2
Resources for viewing maintenance windows for a Vitess database (Enterprise only).
- name: Metrics
description: |2
Resources for retrieving database metrics.
- name: OAuth applications
description: |2
Resources for managing OAuth applications.
- name: OAuth tokens
description: |2
Resources for managing OAuth tokens.
- name: Organization members
description: |2
Resources for managing organization members and their roles.
- name: Organizations
description: |2
Resources for managing organizations.
- name: Bouncer resizes
description: |2
Resources for managing Postgres bouncer resize requests.
- name: Bouncers
description: |2
Resources for managing postgres bouncers.
- name: Switchovers
description: |2
Resources for moving the primary of a Postgres branch.
- name: Query Insights reports
description: |2
Resources for downloading query insights data.
- name: Read-only replicas
description: |2
Resources for managing Postgres read-only replicas.
- name: Roles
description: |2
Resources for managing role credentials.
- name: Schema recommendations
description: |2
Resources for managing schema recommendations within a database.
- name: Service tokens
description: |2
API endpoints for managing service tokens within an organization.
- name: Shard config changes
description: |2
Resources for managing shard-level configuration change requests.
Only available for custom-sharded keyspaces.
- name: Traffic budgets
description: |2
Resources for managing traffic budgets.
- name: Traffic rules
description: |2
Resources for managing traffic rules for a traffic budget.
- name: Users
description: |2
Resources for managing users.
- name: Workflows
description: |2
API endpoints for managing workflows.
- name: Deploy requests
description: |2
Resources for managing deploy requests.
- name: Webhooks
description: |2
Resources for managing database webhooks.
- name: AuthAttemptExports
description: |2
Resources for creating and downloading organization auth attempt exports.
- name: Billing payment method setup
description: |2
Resources for adding an organization's payment method through hosted checkout.
- name: Billing payment method
description: |2
Resources for managing an organization's payment method.
- name: Invoices
description: |2
Resources for managing invoices.
- name: Organization SSO domains
description: |2
Resources for listing and verifying organization email domains used for SSO.
- name: Organization SSO
description: |2
Resources for enabling SSO, verifying email domains, and configuring an identity provider.
- name: Team members
description: |2
Resources for managing team memberships within an organization. Team members inherit access to databases assigned to their team.
Note: Teams managed through SSO/directory services cannot have members added or removed via API.
- name: Organization teams
description: |2
Resources for managing teams within an organization. Teams allow you to group members and grant them access to specific databases.
Note: Teams managed through SSO/directory services cannot be modified via API.
security:
- oauth2: []
x-readme:
explorer-enabled: false
servers:
- url: https://api.planetscale.com/v1
components:
requestBodies:
create_traffic_budgetBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the traffic budget
mode:
type: string
enum:
- enforce
- warn
- off
description: The mode of the traffic budget
capacity:
type: integer
description: The maximum capacity that can be banked, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
rate:
type: integer
description: The rate at which capacity refills, as a percentage of server resources (0-100). Unlimited when not set.
burst:
type: integer
description: The maximum capacity a single query can consume, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
concurrency:
type: integer
description: The percentage of available worker processes this policy can use (0-100). Unlimited when not set.
warning_threshold:
type: integer
description: A percentage of capacity, burst, or concurrency thresholds to emit warnings for enforced budgets (0-100).
rules:
type: array
items:
type: string
description: Array of traffic rules to apply to the budget
create_backup_policyBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
enum:
- hour
- day
- week
- month
- year
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
enum:
- hour
- day
- week
- month
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.planetscale.com/oauth/authorize
tokenUrl: https://auth.planetscale.com/oauth/token
scopes:
email: Read user email
openid: OpenID Connect scope
profile: Read user profile
read_databases: Read organization databases
read_user: Read user
read_organization: Read organization
write_databases: Write organization databases
write_user: Write user
write_organization: Write organization
branch:delete_backups: Delete backups
branch:delete_branch: Delete a database branch
branch:manage_passwords: Read, write, and delete branch passwords
branch:manage_read_only_passwords: Read, write, and delete read only branch passwords
branch:read_backups: Read backups
branch:read_branch: Read a database branch
branch:restore_backups: Restore this branch's backups to new branches
branch:write_backups: Create and update backups
branch:write_branch: Write a database branch
database:approve_deploy_requests: Approve deploy requests in a database
database:delete_backups: Delete backups
database:delete_branches: Delete database branches
database:delete_database: Delete a database
database:delete_members: Delete members
database:delete_production_branch_backups: Delete production backups
database:delete_production_branches: Delete a production database branch
database:demote_branches: Demote production database branches
database:deploy_deploy_requests: Deploy deploy requests in a database
database:manage_passwords: Read, write, and delete database branch passwords
database:manage_production_branch_passwords: Read, write, and delete production branch passwords
database:manage_production_read_only_passwords: Read, write, and delete production read only branch passwords in an organization
database:manage_read_only_passwords: Read, write, and delete read only branch passwords in an organization
database:promote_branches: Promote database branches
database:read_backups: Read backups
database:read_branches: Read database branches
database:read_comments: Read deploy request comments in a database
database:read_database: Read database information
database:read_deploy_requests: Read deploy requests in a database
database:read_members: Read members
database:restore_backups: Restore backups to new branches
database:restore_production_branch_backups: Restore production branch backups to new branches
database:write_backups: Create and update backups
database:write_branches: Write database branches
database:write_comments: Create deploy request comments in a database
database:write_database: Write database
database:write_deploy_requests: Create and update deploy requests in a database
database:write_members: Write members
organization:approve_deploy_requests: Approve deploy requests in an organization
organization:create_databases: Create organization databases
organization:delete_backups: Delete backups in an organization
organization:delete_branches: Delete branches in an organization
organization:delete_databases: Delete organization databases
organization:delete_members: Delete members in an organization
organization:delete_organization: Delete organization
organization:delete_production_branch_backups: Delete production backups in an organization
organization:delete_production_branches: Delete a production branch in an organization
organization:deploy_deploy_requests: Deploy deploy requests in an organization
organization:manage_passwords: Read, write, and delete branch passwords in an organization
organization:manage_production_branch_passwords: Read, write, and delete production branch passwords in an organization
organization:manage_production_read_only_passwords: Read, write, and delete production read only branch passwords in an organization
organization:manage_read_only_passwords: Read, write, and delete read only branch passwords in an organization
organization:manage_sso: Enable, configure, and disable organization SSO
organization:promote_branches: Promote branches in an organization
organization:read_audit_logs: Read organization audit logs
organization:read_backups: Read backups in an organization
organization:read_branches: Read branches in an organization
organization:read_comments: Read deploy request comments in an organization
organization:read_databases: Read organization databases
organization:read_deploy_requests: Read deploy requests in an organization
organization:read_invoices: Read organization invoices
organization:read_members: Read members in an organization
organization:read_organization: Read organization
organization:read_payment_method: Read organization payment method
organization:restore_backups: Restore backups to new branches in an organization
organization:restore_production_branch_backups: Restore production branch backups to new branches in an organization
organization:write_backups: Create and update backups in an organization
organization:write_branches: Write branches in an organization
organization:write_comments: Create deploy request comments in an organization
organization:write_databases: Write organization databases
organization:write_deploy_requests: Create and update deploy requests in an organization
organization:write_members: Write members in an organization
organization:write_organization: Write organization
organization:write_payment_method: Update and delete the organization payment method
user:read_organizations: Read a user's organizations
user:read_user: Read user
user:write_user: Write user
schemas:
OrganizationTeam:
type: object
properties:
id:
type: string
description: The ID of the team
display_name:
type: string
description: The display name of the team
creator:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
members:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
analyst_databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
name:
type: string
description: The name of the team
slug:
type: string
description: The slug of the team
created_at:
type: string
description: When the team was created
updated_at:
type: string
description: When the team was last updated
description:
type: string
description: The description of the team
nullable: true
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
required:
- id
- display_name
- creator
- members
- databases
- analyst_databases
- name
- slug
- created_at
- updated_at
- description
- managed
PaginatedOrganizationTeam:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the team
display_name:
type: string
description: The display name of the team
creator:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
members:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
analyst_databases:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
name:
type: string
description: The name of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
required:
- id
- name
- url
- branches_url
name:
type: string
description: The name of the team
slug:
type: string
description: The slug of the team
created_at:
type: string
description: When the team was created
updated_at:
type: string
description: When the team was last updated
description:
type: string
description: The description of the team
nullable: true
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
required:
- id
- display_name
- creator
- members
- databases
- analyst_databases
- name
- slug
- created_at
- updated_at
- description
- managed
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
OrganizationTeamMembership:
type: object
properties:
id:
type: string
description: The ID of the team membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
passwords:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: The list of hosts in each availability zone providing direct access to a vtgate
ttl_seconds:
type: integer
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plaintext password. Null except in the response from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
required:
- id
- user
- actor
- created_at
- updated_at
- passwords
PaginatedOrganizationTeamMembership:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the team membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
passwords:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: The list of hosts in each availability zone providing direct access to a vtgate
ttl_seconds:
type: integer
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plaintext password. Null except in the response from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
required:
- id
- user
- actor
- created_at
- updated_at
- passwords
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
OrganizationSsoSerializer:
type: object
properties:
type:
type: string
enum:
- OrganizationSSO
description: The resource type
id:
type: string
description: The organization ID
enabled:
type: boolean
description: Whether the SSO add-on is enabled for the organization
configured:
type: boolean
description: Whether an identity provider connection is active
directory:
type: boolean
description: Whether directory sync is enabled
has_verified_domain:
type: boolean
description: Whether the organization has at least one verified email domain
domains:
type: array
items:
type: object
properties:
type:
type: string
enum:
- OrganizationDomain
description: The resource type
id:
type: string
description: The public ID of the organization domain
domain:
type: string
description: The domain name
state:
type: string
enum:
- pending
- verified
- failed
description: The verification state of the domain
verified_at:
type: string
description: When the domain was verified
nullable: true
failure_reason:
type: string
description: The reason domain verification failed
nullable: true
created_at:
type: string
description: When the domain was created
updated_at:
type: string
description: When the domain was last updated
required:
- type
- id
- domain
- state
- verified_at
- failure_reason
- created_at
- updated_at
domain_verification_url:
type: string
description: URL to open for verifying an email domain, returned when SSO is enabled
nullable: true
required:
- type
- id
- enabled
- configured
- directory
- has_verified_domain
- domains
- domain_verification_url
OrganizationDomain:
type: object
properties:
type:
type: string
enum:
- OrganizationDomain
description: The resource type
id:
type: string
description: The public ID of the organization domain
domain:
type: string
description: The domain name
state:
type: string
enum:
- pending
- verified
- failed
description: The verification state of the domain
verified_at:
type: string
description: When the domain was verified
nullable: true
failure_reason:
type: string
description: The reason domain verification failed
nullable: true
created_at:
type: string
description: When the domain was created
updated_at:
type: string
description: When the domain was last updated
required:
- type
- id
- domain
- state
- verified_at
- failure_reason
- created_at
- updated_at
Invoice:
type: object
properties:
id:
type: string
description: The ID of the invoice
total:
type: string
description: The total amount of the invoice, as a stringified decimal to preserve precision
billing_period_start:
type: string
description: Start of the billing period
billing_period_end:
type: string
description: End of the billing period
paid:
type: boolean
description: Whether the invoice has been paid
overdue:
type: boolean
description: Whether the invoice is past due and unpaid
required:
- id
- total
- billing_period_start
- billing_period_end
- paid
- overdue
PaginatedInvoice:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the invoice
total:
type: string
description: The total amount of the invoice, as a stringified decimal to preserve precision
billing_period_start:
type: string
description: Start of the billing period
billing_period_end:
type: string
description: End of the billing period
paid:
type: boolean
description: Whether the invoice has been paid
overdue:
type: boolean
description: Whether the invoice is past due and unpaid
required:
- id
- total
- billing_period_start
- billing_period_end
- paid
- overdue
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedLineItem:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the line item
subtotal:
type: number
description: The total for the line item
description:
type: string
description: The description for the line item
metric_name:
type: string
description: The name of the billable item
cloudflare_billed:
type: boolean
description: Whether the line item is billed through Cloudflare
database_id:
type: string
description: The ID for the billed database
database_name:
type: string
description: The name for the billed database
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- subtotal
- description
- metric_name
- cloudflare_billed
- database_id
- database_name
- resource
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
BillingPaymentMethod:
type: object
properties:
type:
type: string
enum:
- PaymentMethod
description: The resource type
id:
type: string
description: The payment method ID
brand:
type: string
description: The card brand, such as visa or mastercard
last4:
type: string
description: The final four digits of the card number
exp_month:
type: integer
description: The card expiration month
exp_year:
type: integer
description: The card expiration year
name:
type: string
description: The cardholder name
nullable: true
required:
- type
- id
- brand
- last4
- exp_month
- exp_year
- name
BillingPaymentMethodSetup:
type: object
properties:
type:
type: string
enum:
- BillingPaymentMethodSetup
description: The resource type
id:
type: string
description: The billing payment method setup ID
state:
type: string
enum:
- pending
- completed
- failed
- expired
description: The setup state
checkout_url:
type: string
description: The hosted checkout URL while the setup is pending
nullable: true
error:
type: string
description: The failure message when the setup failed
nullable: true
expires_at:
type: string
description: When the pending setup expires
nullable: true
completed_at:
type: string
description: When the setup completed
nullable: true
failed_at:
type: string
description: When the setup failed
nullable: true
required:
- type
- id
- state
- checkout_url
- error
- expires_at
- completed_at
- failed_at
DatabaseWebhook:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
nullable: true
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- backup.failed
- backup.succeeded
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
PaginatedDatabaseWebhook:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
nullable: true
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- backup.failed
- backup.succeeded
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
DatabaseDeployRequest:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
PaginatedDeployment:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedDeployOperation:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
Deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
PaginatedDatabaseDeployRequest:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
nullable: true
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
into_branch_keyspace_count:
type: integer
description: The number of keyspaces the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
nullable: true
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment.
nullable: true
finished_at:
type: string
description: When the deployment was finished
nullable: true
force_cutover_requested_at:
type: string
description: When force cutover was triggered for the deployment
nullable: true
queued_at:
type: string
description: When the deployment was queued
nullable: true
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
nullable: true
started_at:
type: string
description: When the deployment was started
nullable: true
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
nullable: true
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: integer
description: The number of the deploy request associated with this deployment
deployable:
type: boolean
description: Whether the deployment is deployable
preceding_deployments:
items:
type: object
additionalProperties: true
type: array
description: The deployments ahead of this one in the queue
deploy_operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
nullable: true
progress_percentage:
type: number
description: The percent completion for the deploy operation
nullable: true
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
nullable: true
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
nullable: true
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
nullable: true
deploy_errors:
type: string
description: Deploy errors for the deploy operation
nullable: true
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation summary
keyspace_name:
type: string
description: The keyspace modified by the deploy operation summary
operation_name:
type: string
description: The operation name of the deploy operation summary
progress_percentage:
type: number
description: The percent completion for the deploy operation summary
state:
type: string
enum:
- pending
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation summary
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation summary
table_name:
type: string
description: The name of the table modifed by the deploy operation summary
table_recently_used_at:
type: string
description: When the table modified by the deploy operation summary was last used
nullable: true
throttled_at:
type: string
description: When the deploy operation summary was last throttled
nullable: true
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: integer
description: The number of shards in the keyspace modified by the deploy operation summary
shard_names:
items:
type: string
type: array
description: Names of shards in the keyspace modified by the deploy operation summary
can_drop_data:
type: boolean
description: Whether or not the deploy operation summary is capable of dropping data
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation summary was recently used
sharded:
type: boolean
description: Whether or not the keyspace modified by the deploy operation summary is sharded
operations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
shard:
type: string
description: The shard the deploy operation is being performed on
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
eta_seconds:
type: integer
description: The estimated seconds until completion for the deploy operation
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
type: object
additionalProperties: true
description: Deployment throttling configurations.
nullable: true
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
nullable: true
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of the table that is locked by the deployment.
nullable: true
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
queue_paused:
type: boolean
description: Whether the deploy queue for the target branch is currently paused
queue_pause_reason:
type: string
description: A human-readable reason the deploy queue is paused, if known
nullable: true
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- finished_at
- force_cutover_requested_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- deployment_revert_request
- schema_last_updated_at
- table_locked
- instant_ddl
- instant_ddl_eligible
- queue_paused
- queue_pause_reason
num_comments:
type: integer
description: The number of comments on the deploy request
html_url:
type: string
description: The PlanetScale app address for the deploy request
notes:
type: string
description: Notes on the deploy request
html_body:
type: string
description: The HTML body of the deploy request
created_at:
type: string
description: When the deploy request was created
updated_at:
type: string
description: When the deploy request was last updated
closed_at:
type: string
description: When the deploy request was closed
nullable: true
deployed_at:
type: string
description: When the deploy request was deployed
nullable: true
required:
- id
- number
- actor
- branch
- branch_id
- branch_deleted
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- into_branch_keyspace_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
ThrottlerConfigurations:
type: object
properties:
keyspaces:
items:
type: string
type: array
description: Keyspaces that are eligible for throttler configuration in the configurable resource (database or deploy request)
configurable:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: A throttler ratio between 0 and 95 that applies to migrations in this specific keyspace
required:
- keyspace_name
- ratio
required:
- keyspaces
- configurable
- configurations
DeployRequestReview:
type: object
properties:
id:
type: string
description: The ID of the review
body:
type: string
description: The text body of the review
html_body:
type: string
description: The HTML body of the review
state:
type: string
enum:
- commented
- approved
description: Whether the review is a comment or approval
created_at:
type: string
description: When the review was created
updated_at:
type: string
description: When the review was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- body
- html_body
- state
- created_at
- updated_at
- actor
PaginatedDeployRequestReview:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the review
body:
type: string
description: The text body of the review
html_body:
type: string
description: The HTML body of the review
state:
type: string
enum:
- commented
- approved
description: Whether the review is a comment or approval
created_at:
type: string
description: When the review was created
updated_at:
type: string
description: When the review was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- body
- html_body
- state
- created_at
- updated_at
- actor
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
Workflow:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
PaginatedWorkflow:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: integer
description: The sequence number of the workflow
state:
type: string
enum:
- pending
- copying
- running
- stopped
- verifying_data
- verified_data
- switching_replicas
- switched_replicas
- switching_primaries
- switched_primaries
- reversing_traffic
- reversing_traffic_for_cancel
- cutting_over
- cutover
- reversed_cutover
- completed
- cancelling
- cancelled
- error
description: The state of the workflow
created_at:
type: string
description: When the workflow was created
updated_at:
type: string
description: When the workflow was last updated
started_at:
type: string
description: When the workflow was started
nullable: true
completed_at:
type: string
description: When the workflow was completed
nullable: true
cancelled_at:
type: string
description: When the workflow was cancelled
nullable: true
reversed_at:
type: string
description: When the workflow was reversed
nullable: true
retried_at:
type: string
description: When the workflow was retried
nullable: true
data_copy_completed_at:
type: string
description: When the data copy was completed
nullable: true
cutover_at:
type: string
description: When the cutover was completed
nullable: true
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
nullable: true
switch_primaries_at:
type: string
description: When the primaries were switched
nullable: true
verify_data_at:
type: string
description: When the data was verified
nullable: true
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
User:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
TrafficRule:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
- each
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
TrafficBudget:
type: object
properties:
id:
type: string
description: The ID of the traffic budget
name:
type: string
description: The name of the budget
mode:
type: string
enum:
- enforce
- warn
- off
description: The mode of the budget
capacity:
type: number
description: The maximum capacity that can be banked, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
rate:
type: number
description: The rate at which capacity refills, as a percentage of server resources (0-100). Unlimited when not set.
nullable: true
burst:
type: number
description: The maximum capacity a single query can consume, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
concurrency:
type: number
description: The percentage of available worker processes this policy can use (0-100). Unlimited when not set.
nullable: true
warning_threshold:
type: number
description: A percentage of capacity, burst, or concurrency thresholds to emit warnings for enforced budgets (0-100).
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
rules:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
- each
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
created_at:
type: string
description: When the budget was created
updated_at:
type: string
description: When the budget was updated
required:
- id
- name
- mode
- actor
- rules
- created_at
- updated_at
PaginatedTrafficBudget:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic budget
name:
type: string
description: The name of the budget
mode:
type: string
enum:
- enforce
- warn
- off
description: The mode of the budget
capacity:
type: number
description: The maximum capacity that can be banked, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
rate:
type: number
description: The rate at which capacity refills, as a percentage of server resources (0-100). Unlimited when not set.
nullable: true
burst:
type: number
description: The maximum capacity a single query can consume, measured as a percentage of seconds of full server usage (0-6000). Unlimited when not set.
nullable: true
concurrency:
type: number
description: The percentage of available worker processes this policy can use (0-100). Unlimited when not set.
nullable: true
warning_threshold:
type: number
description: A percentage of capacity, burst, or concurrency thresholds to emit warnings for enforced budgets (0-100).
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
rules:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the traffic rule
kind:
type: string
enum:
- match
- each
description: The kind of rule
tags:
type: array
items:
type: object
properties:
key_id:
type: string
description: The ID of the key for this tag
key:
type: string
description: The key for this tag
value:
type: string
description: The value for this tag
source:
type: string
enum:
- sql
- system
description: The source of this tag
required:
- key_id
- key
- value
- source
fingerprint:
type: string
description: The query fingerprint targeted by this rule
nullable: true
keyspace:
type: string
description: The keyspace of the fingerprint
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL for rules with SQL keys
created_at:
type: string
description: When the rule was created
updated_at:
type: string
description: When the rule was updated
required:
- id
- kind
- tags
- actor
- syntax_highlighted_sql
- created_at
- updated_at
created_at:
type: string
description: When the budget was created
updated_at:
type: string
description: When the budget was updated
required:
- id
- name
- mode
- actor
- rules
- created_at
- updated_at
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
ServiceToken:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
nullable: true
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
nullable: true
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
PaginatedServiceToken:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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
nullable: true
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
nullable: true
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
nullable: true
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
nullable: true
last_used_at:
type: string
description: When the service token was last used
nullable: true
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
nullable: true
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
nullable: true
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
nullable: true
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
nullable: true
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
required:
- name
- description
required:
- users
- accesses
required:
- database
- organization
- branch
- user
nullable: true
required:
- id
- name
- display_name
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
SchemaRecommendation:
type: object
properties:
id:
type: string
description: The ID of the schema recommendation
html_url:
type: string
description: The URL to the schema recommendation in the app
title:
type: string
description: The title of the schema recommendation
table_name:
type: string
description: The name of the table the recommendation applies to
keyspace:
type: string
description: The keyspace the recommendation applies to
ddl_statement:
type: string
description: The DDL statement to apply the recommendation
number:
type: integer
description: The number of the schema recommendation
state:
type: string
enum:
- open
- applied
- dismissed
- stale
description: The state of the recommendation
recommendation_type:
type: string
enum:
- unused_table
- unused_index
- duplicate_index
- sequence_overflow
- sequence_overflow_foreign_key
- new_index
- encoding_upgrade
- bloated_table
- bloated_index
description: The type of recommendation
created_at:
type: string
description: When the recommendation was created
updated_at:
type: string
description: When the recommendation was last updated
applied_at:
type: string
description: When the recommendation was applied
nullable: true
dismissed_at:
type: string
description: When the recommendation was dismissed
nullable: true
closed_by_deploy_request:
type: object
properties:
id:
type: string
description: The ID of the deploy request
branch_id:
type: string
description: The ID of the branch
number:
type: integer
description: The number of the deploy request
required:
- id
- branch_id
- number
nullable: true
dismissed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
required:
- id
- html_url
- title
- table_name
- keyspace
- ddl_statement
- number
- state
- recommendation_type
- created_at
- updated_at
- applied_at
- dismissed_at
- closed_by_deploy_request
- dismissed_by
PaginatedSchemaRecommendation:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the schema recommendation
html_url:
type: string
description: The URL to the schema recommendation in the app
title:
type: string
description: The title of the schema recommendation
table_name:
type: string
description: The name of the table the recommendation applies to
keyspace:
type: string
description: The keyspace the recommendation applies to
ddl_statement:
type: string
description: The DDL statement to apply the recommendation
number:
type: integer
description: The number of the schema recommendation
state:
type: string
enum:
- open
- applied
- dismissed
- stale
description: The state of the recommendation
recommendation_type:
type: string
enum:
- unused_table
- unused_index
- duplicate_index
- sequence_overflow
- sequence_overflow_foreign_key
- new_index
- encoding_upgrade
- bloated_table
- bloated_index
description: The type of recommendation
created_at:
type: string
description: When the recommendation was created
updated_at:
type: string
description: When the recommendation was last updated
applied_at:
type: string
description: When the recommendation was applied
nullable: true
dismissed_at:
type: string
description: When the recommendation was dismissed
nullable: true
closed_by_deploy_request:
type: object
properties:
id:
type: string
description: The ID of the deploy request
branch_id:
type: string
description: The ID of the branch
number:
type: integer
description: The number of the deploy request
required:
- id
- branch_id
- number
nullable: true
dismissed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
required:
- id
- html_url
- title
- table_name
- keyspace
- ddl_statement
- number
- state
- recommendation_type
- created_at
- updated_at
- applied_at
- dismissed_at
- closed_by_deploy_request
- dismissed_by
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
PostgresRole:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plaintext password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
ready:
type: boolean
description: Whether the role is ready to accept connections
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- 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
with_replication:
type: boolean
description: Whether the role has the REPLICATION attribute
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- ready
- expired
- default
- ttl
- inherited_roles
- with_replication
- branch
- actor
- query_safety_settings
PaginatedPostgresRole:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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
base_username:
type: string
description: The base username without branch routing suffix
password:
type: string
description: The plaintext password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
nullable: true
expires_at:
type: string
description: When the role expires
nullable: true
dropped_at:
type: string
description: When the role was dropped
nullable: true
disabled_at:
type: string
description: When the role was disabled
nullable: true
drop_failed:
type: string
description: Error message available when dropping the role fails
ready:
type: boolean
description: Whether the role is ready to accept connections
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- 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
with_replication:
type: boolean
description: Whether the role has the REPLICATION attribute
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
query_safety_settings:
type: object
properties:
require_where_on_delete:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
enum:
- off
- warn
- on
description: Require WHERE clause on UPDATE statements
required:
- require_where_on_delete
- require_where_on_update
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- base_username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- ready
- expired
- default
- ttl
- inherited_roles
- with_replication
- branch
- actor
- query_safety_settings
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
PaginatedPublicPlanetscaleRegionSerializer:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: The cloud provider for the region
enabled:
type: boolean
description: Whether new clusters can be created in this region
public_ip_addresses:
items:
type: string
type: array
description: List of public IP addresses for the region
display_name:
type: string
description: The name of the region
location:
type: string
description: The location of the region
slug:
type: string
description: The slug identifier for the region
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PostgresReadOnlyReplica:
type: object
properties:
id:
type: string
description: The ID of the read-only replica
name:
type: string
description: The name of the read-only replica
state:
type: string
description: "The state of the read-only replica: pending, ready, or deleting"
replicas:
type: integer
description: The number of instances serving reads in this read-only replica
cluster_name:
type: string
description: The SKU representing the cluster size of the read-only replica
cluster_display_name:
type: string
description: The SKU representing the cluster size of the read-only replica, for display
access_host_url:
type: string
description: The database connection host for the read-only replica
private_access_host_url:
type: string
description: The private database connection host for the read-only replica
private_connection_service_name:
type: string
description: The service name to set up private connectivity for the read-only replica
nullable: true
created_at:
type: string
description: When the read-only replica was created
updated_at:
type: string
description: When the read-only replica was last updated
ready_at:
type: string
description: When the read-only replica was ready to serve queries
nullable: true
ready:
type: boolean
description: Whether or not the read-only replica is ready to serve queries
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgconf
description: The namespace of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- integer
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter, which is the primary's current value
disabled_reason:
type: string
description: Why the parameter cannot be changed
nullable: true
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
nullable: true
updated_at:
type: string
description: When the parameter was last updated
nullable: true
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter, floored at the primary's current value
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
units:
items:
type: string
type: array
description: Display units for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- namespace
- name
- display_name
- category
- description
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- url
- options
- units
- actor
required:
- id
- name
- state
- replicas
- cluster_name
- cluster_display_name
- access_host_url
- private_access_host_url
- private_connection_service_name
- created_at
- updated_at
- ready_at
- ready
- actor
- region
- parameters
PaginatedPostgresReadOnlyReplicaChangeRequest:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the read-only replica change request
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the change request
cluster_name:
type: string
description: The new cluster size SKU
cluster_display_name:
type: string
description: The new cluster size for display
cluster_rank:
type: integer
description: The new cluster size sort order
replicas:
type: integer
description: The new instance count
parameters:
type: object
additionalProperties: true
description: The new parameters
previous_cluster_name:
type: string
description: The previous cluster size SKU
previous_cluster_display_name:
type: string
description: The previous cluster size for display
previous_cluster_rank:
type: integer
description: The previous cluster size sort order
previous_replicas:
type: integer
description: The previous instance count
previous_parameters:
type: object
additionalProperties: true
description: The previous parameters
started_at:
type: string
description: When the change started
nullable: true
completed_at:
type: string
description: When the change completed
nullable: true
created_at:
type: string
description: When the change request was created
updated_at:
type: string
description: When the change request was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
replica:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
required:
- id
- state
- cluster_name
- cluster_display_name
- cluster_rank
- replicas
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_rank
- previous_replicas
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- replica
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
QueryPatternsDownload:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
nullable: true
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- created_at
- finished_at
- url
- download_url
- actor
PaginatedQueryPatternsDownload:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
has_next:
type: boolean
description: Whether there is a next page of results
has_prev:
type: boolean
description: Whether there is a previous page of results
cursor_start:
type: string
description: The ID of the first object in the current results, or null when there are no results
nullable: true
cursor_end:
type: string
description: The ID of the last object in the current results, or null when there are no results
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
nullable: true
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- created_at
- finished_at
- url
- download_url
- actor
required:
- type
- has_next
- has_prev
- cursor_start
- cursor_end
- data
QueryTag:
type: object
properties:
id:
type: string
description: The ID of the tag
name:
type: string
description: The name of the tag
source:
type: string
enum:
- sql
- system
description: The source of the tag
query_count:
type: integer
description: The number of queries that have this tag
values:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the tag value
query_count:
type: integer
description: The number of queries that have this tag value
kind:
type: string
enum:
- literal
- overflow
- collapsed
description: The kind of tag value
required:
- name
- query_count
- kind
required:
- id
- name
- source
- query_count
- values
PaginatedDimensionsQuerySummary:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
dimensions:
type: object
additionalProperties: true
description: The tag names and values this summary is grouped by
query_count:
type: integer
description: The number of times this query was executed
error_count:
type: integer
description: The number of times this query resulted in an error
tables:
items:
type: string
type: array
description: Tables accessed by the query
qualified_tables:
items:
type: string
type: array
description: Fully qualified tables accessed by the query
table_keyspaces:
items:
type: object
additionalProperties: true
type: array
description: Mapping of tables to their keyspaces
index_usages:
items:
type: object
additionalProperties: true
type: array
description: Index usage information
routing_index_usages:
items:
type: object
additionalProperties: true
type: array
description: Routing index usage information
sum_shard_queries:
type: integer
description: The total number of shard queries
max_shard_queries:
type: integer
description: The maximum number of shard queries for a single execution
avg_shard_queries:
type: number
description: The average number of shard queries
avg_parallel_workers:
type: number
description: The average number of parallel workers
sum_rows_read:
type: integer
description: The total number of rows read
sum_rows_affected:
type: integer
description: The total number of rows affected
sum_rows_returned:
type: integer
description: The total number of rows returned
rows_read_per_returned:
type: number
description: Average rows read per row returned
rows_read_per_query:
type: number
description: Average rows read per query
rows_returned_per_query:
type: number
description: Average rows returned per query
rows_affected_per_query:
type: number
description: Average rows affected per query
sum_total_duration_millis:
type: integer
description: Total duration in milliseconds across all executions
sum_total_duration_percent:
type: number
description: Percentage of total query time
sum_cpu_duration_millis:
type: integer
description: Total CPU duration in milliseconds
sum_cpu_duration_percent:
type: number
description: Percentage of total CPU time
sum_io_duration_millis:
type: integer
description: Total IO duration in milliseconds
sum_io_duration_percent:
type: number
description: Percentage of total IO time
last_run_at:
type: string
description: When this query was last executed
nullable: true
time_per_query:
type: number
description: Average time per query execution
p50_latency:
type: number
description: 50th percentile latency
p99_latency:
type: number
description: 99th percentile latency
max_latency:
type: number
description: Maximum latency observed
egress_bytes:
type: integer
description: Total egress bytes
egress_bytes_per_query:
type: number
description: Average egress bytes per query
max_egress_bytes:
type: integer
description: Maximum egress bytes for a single execution
ingress_bytes:
type: integer
description: Total ingress bytes
ingress_bytes_per_query:
type: number
description: Average ingress bytes per query
max_ingress_bytes:
type: integer
description: Maximum ingress bytes for a single execution
blocks_read:
type: integer
description: Total blocks read from disk
blocks_hit:
type: integer
description: Total blocks found in cache
block_cache_hit_ratio:
type: number
description: Cache hit ratio for blocks
blocks_dirtied:
type: integer
description: Total blocks dirtied
blocks_written:
type: integer
description: Total blocks written
traffic_control_warnings:
type: integer
description: The number of executions that triggered a traffic control warning
traffic_control_throttled:
type: integer
description: The number of executions throttled by traffic control
traffic_control_checked:
type: integer
description: The number of executions checked by traffic control rules
required:
- dimensions
- query_count
- error_count
- tables
- qualified_tables
- table_keyspaces
- index_usages
- routing_index_usages
- sum_shard_queries
- max_shard_queries
- avg_shard_queries
- avg_parallel_workers
- sum_rows_read
- sum_rows_affected
- sum_rows_returned
- rows_read_per_returned
- rows_read_per_query
- rows_returned_per_query
- rows_affected_per_query
- sum_total_duration_millis
- sum_total_duration_percent
- sum_cpu_duration_millis
- sum_cpu_duration_percent
- sum_io_duration_millis
- sum_io_duration_percent
- last_run_at
- time_per_query
- p50_latency
- p99_latency
- max_latency
- egress_bytes
- egress_bytes_per_query
- max_egress_bytes
- ingress_bytes
- ingress_bytes_per_query
- max_ingress_bytes
- blocks_read
- blocks_hit
- block_cache_hit_ratio
- blocks_dirtied
- blocks_written
- traffic_control_warnings
- traffic_control_throttled
- traffic_control_checked
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedQueryTag:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the tag
name:
type: string
description: The name of the tag
source:
type: string
enum:
- sql
- system
description: The source of the tag
query_count:
type: integer
description: The number of queries that have this tag
values:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the tag value
query_count:
type: integer
description: The number of queries that have this tag value
kind:
type: string
enum:
- literal
- overflow
- collapsed
description: The kind of tag value
required:
- name
- query_count
- kind
required:
- id
- name
- source
- query_count
- values
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedQuery:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the query
password:
type: object
additionalProperties: true
description: The database password used for the query
tags:
items:
type: object
additionalProperties: true
type: array
description: Tags associated with the query
fingerprint:
type: string
description: The query fingerprint
started_at:
type: string
description: When the query started
nullable: true
statement_type:
type: string
description: The type of SQL statement
keyspace:
type: string
description: The keyspace the query ran against
tables:
items:
type: string
type: array
description: Tables accessed by the query
username:
type: string
description: The username that executed the query
remote_address:
type: string
description: The remote IP address of the client
shard_queries:
type: integer
description: The number of shard queries executed
rows_read:
type: integer
description: The number of rows read
rows_affected:
type: integer
description: The number of rows affected
rows_returned:
type: integer
description: The number of rows returned
total_duration_millis:
type: integer
description: Total query duration in milliseconds
error_message:
type: string
description: Error message if the query failed
normalized_sql:
type: string
description: The normalized SQL statement
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL statement
created_at:
type: string
description: When the query record was created
updated_at:
type: string
description: When the query record was last updated
explainable:
type: boolean
description: Whether the query can be explained
truncated:
type: boolean
description: Whether the query was truncated
required:
- id
- password
- tags
- fingerprint
- started_at
- statement_type
- keyspace
- tables
- username
- remote_address
- shard_queries
- rows_read
- rows_affected
- rows_returned
- total_duration_millis
- error_message
- normalized_sql
- syntax_highlighted_sql
- created_at
- updated_at
- explainable
- truncated
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedErrorSummary:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the error summary
error_fingerprint:
type: string
description: The error fingerprint
started_at:
type: string
description: When the error last occurred
total_duration_millis:
type: integer
description: Total duration in milliseconds across all failed executions
time_per_query:
type: number
description: Average duration per failed execution in milliseconds
error_count:
type: integer
description: The number of times the error occurred
error_message:
type: string
description: The error message
required:
- id
- error_fingerprint
- started_at
- total_duration_millis
- time_per_query
- error_count
- error_message
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
Query:
type: object
properties:
id:
type: string
description: The ID of the query
password:
type: object
additionalProperties: true
description: The database password used for the query
tags:
items:
type: object
additionalProperties: true
type: array
description: Tags associated with the query
fingerprint:
type: string
description: The query fingerprint
started_at:
type: string
description: When the query started
nullable: true
statement_type:
type: string
description: The type of SQL statement
keyspace:
type: string
description: The keyspace the query ran against
tables:
items:
type: string
type: array
description: Tables accessed by the query
username:
type: string
description: The username that executed the query
remote_address:
type: string
description: The remote IP address of the client
shard_queries:
type: integer
description: The number of shard queries executed
rows_read:
type: integer
description: The number of rows read
rows_affected:
type: integer
description: The number of rows affected
rows_returned:
type: integer
description: The number of rows returned
total_duration_millis:
type: integer
description: Total query duration in milliseconds
error_message:
type: string
description: Error message if the query failed
normalized_sql:
type: string
description: The normalized SQL statement
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL statement
created_at:
type: string
description: When the query record was created
updated_at:
type: string
description: When the query record was last updated
explainable:
type: boolean
description: Whether the query can be explained
truncated:
type: boolean
description: Whether the query was truncated
required:
- id
- password
- tags
- fingerprint
- started_at
- statement_type
- keyspace
- tables
- username
- remote_address
- shard_queries
- rows_read
- rows_affected
- rows_returned
- total_duration_millis
- error_message
- normalized_sql
- syntax_highlighted_sql
- created_at
- updated_at
- explainable
- truncated
QuerySummary:
type: object
properties:
id:
type: string
description: The ID of the query summary
fingerprint:
type: string
description: The query fingerprint
statement_type:
type: string
description: The type of SQL statement
keyspace:
type: string
description: The keyspace the query ran against
normalized_sql:
type: string
description: The normalized SQL statement
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL statement
multishard:
type: boolean
description: Whether the query is a multishard query
query_count:
type: integer
description: The number of times this query was executed
error_count:
type: integer
description: The number of times this query resulted in an error
tables:
items:
type: string
type: array
description: Tables accessed by the query
qualified_tables:
items:
type: string
type: array
description: Fully qualified tables accessed by the query
table_keyspaces:
items:
type: object
additionalProperties: true
type: array
description: Mapping of tables to their keyspaces
index_usages:
items:
type: object
additionalProperties: true
type: array
description: Index usage information
routing_index_usages:
items:
type: object
additionalProperties: true
type: array
description: Routing index usage information
sum_shard_queries:
type: integer
description: The total number of shard queries
max_shard_queries:
type: integer
description: The maximum number of shard queries for a single execution
avg_shard_queries:
type: number
description: The average number of shard queries
avg_parallel_workers:
type: number
description: The average number of parallel workers
sum_rows_read:
type: integer
description: The total number of rows read
sum_rows_affected:
type: integer
description: The total number of rows affected
sum_rows_returned:
type: integer
description: The total number of rows returned
rows_read_per_returned:
type: number
description: Average rows read per row returned
rows_read_per_query:
type: number
description: Average rows read per query
rows_returned_per_query:
type: number
description: Average rows returned per query
rows_affected_per_query:
type: number
description: Average rows affected per query
sum_total_duration_millis:
type: integer
description: Total duration in milliseconds across all executions
sum_total_duration_percent:
type: number
description: Percentage of total query time
sum_cpu_duration_millis:
type: integer
description: Total CPU duration in milliseconds
sum_cpu_duration_percent:
type: number
description: Percentage of total CPU time
sum_io_duration_millis:
type: integer
description: Total IO duration in milliseconds
sum_io_duration_percent:
type: number
description: Percentage of total IO time
last_run_at:
type: string
description: When this query was last executed
nullable: true
time_per_query:
type: number
description: Average time per query execution
p50_latency:
type: number
description: 50th percentile latency
p99_latency:
type: number
description: 99th percentile latency
max_latency:
type: number
description: Maximum latency observed
egress_bytes:
type: integer
description: Total egress bytes
egress_bytes_per_query:
type: number
description: Average egress bytes per query
max_egress_bytes:
type: integer
description: Maximum egress bytes for a single execution
ingress_bytes:
type: integer
description: Total ingress bytes
ingress_bytes_per_query:
type: number
description: Average ingress bytes per query
max_ingress_bytes:
type: integer
description: Maximum ingress bytes for a single execution
blocks_read:
type: integer
description: Total blocks read from disk
blocks_hit:
type: integer
description: Total blocks found in cache
block_cache_hit_ratio:
type: number
description: Cache hit ratio for blocks
blocks_dirtied:
type: integer
description: Total blocks dirtied
blocks_written:
type: integer
description: Total blocks written
traffic_control_warnings:
type: integer
description: The number of executions that triggered a traffic control warning
traffic_control_throttled:
type: integer
description: The number of executions throttled by traffic control
traffic_control_checked:
type: integer
description: The number of executions checked by traffic control rules
required:
- id
- fingerprint
- statement_type
- keyspace
- normalized_sql
- syntax_highlighted_sql
- multishard
- query_count
- error_count
- tables
- qualified_tables
- table_keyspaces
- index_usages
- routing_index_usages
- sum_shard_queries
- max_shard_queries
- avg_shard_queries
- avg_parallel_workers
- sum_rows_read
- sum_rows_affected
- sum_rows_returned
- rows_read_per_returned
- rows_read_per_query
- rows_returned_per_query
- rows_affected_per_query
- sum_total_duration_millis
- sum_total_duration_percent
- sum_cpu_duration_millis
- sum_cpu_duration_percent
- sum_io_duration_millis
- sum_io_duration_percent
- last_run_at
- time_per_query
- p50_latency
- p99_latency
- max_latency
- egress_bytes
- egress_bytes_per_query
- max_egress_bytes
- ingress_bytes
- ingress_bytes_per_query
- max_ingress_bytes
- blocks_read
- blocks_hit
- block_cache_hit_ratio
- blocks_dirtied
- blocks_written
- traffic_control_warnings
- traffic_control_throttled
- traffic_control_checked
PaginatedQuerySummary:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the query summary
fingerprint:
type: string
description: The query fingerprint
statement_type:
type: string
description: The type of SQL statement
keyspace:
type: string
description: The keyspace the query ran against
normalized_sql:
type: string
description: The normalized SQL statement
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL statement
multishard:
type: boolean
description: Whether the query is a multishard query
query_count:
type: integer
description: The number of times this query was executed
error_count:
type: integer
description: The number of times this query resulted in an error
tables:
items:
type: string
type: array
description: Tables accessed by the query
qualified_tables:
items:
type: string
type: array
description: Fully qualified tables accessed by the query
table_keyspaces:
items:
type: object
additionalProperties: true
type: array
description: Mapping of tables to their keyspaces
index_usages:
items:
type: object
additionalProperties: true
type: array
description: Index usage information
routing_index_usages:
items:
type: object
additionalProperties: true
type: array
description: Routing index usage information
sum_shard_queries:
type: integer
description: The total number of shard queries
max_shard_queries:
type: integer
description: The maximum number of shard queries for a single execution
avg_shard_queries:
type: number
description: The average number of shard queries
avg_parallel_workers:
type: number
description: The average number of parallel workers
sum_rows_read:
type: integer
description: The total number of rows read
sum_rows_affected:
type: integer
description: The total number of rows affected
sum_rows_returned:
type: integer
description: The total number of rows returned
rows_read_per_returned:
type: number
description: Average rows read per row returned
rows_read_per_query:
type: number
description: Average rows read per query
rows_returned_per_query:
type: number
description: Average rows returned per query
rows_affected_per_query:
type: number
description: Average rows affected per query
sum_total_duration_millis:
type: integer
description: Total duration in milliseconds across all executions
sum_total_duration_percent:
type: number
description: Percentage of total query time
sum_cpu_duration_millis:
type: integer
description: Total CPU duration in milliseconds
sum_cpu_duration_percent:
type: number
description: Percentage of total CPU time
sum_io_duration_millis:
type: integer
description: Total IO duration in milliseconds
sum_io_duration_percent:
type: number
description: Percentage of total IO time
last_run_at:
type: string
description: When this query was last executed
nullable: true
time_per_query:
type: number
description: Average time per query execution
p50_latency:
type: number
description: 50th percentile latency
p99_latency:
type: number
description: 99th percentile latency
max_latency:
type: number
description: Maximum latency observed
egress_bytes:
type: integer
description: Total egress bytes
egress_bytes_per_query:
type: number
description: Average egress bytes per query
max_egress_bytes:
type: integer
description: Maximum egress bytes for a single execution
ingress_bytes:
type: integer
description: Total ingress bytes
ingress_bytes_per_query:
type: number
description: Average ingress bytes per query
max_ingress_bytes:
type: integer
description: Maximum ingress bytes for a single execution
blocks_read:
type: integer
description: Total blocks read from disk
blocks_hit:
type: integer
description: Total blocks found in cache
block_cache_hit_ratio:
type: number
description: Cache hit ratio for blocks
blocks_dirtied:
type: integer
description: Total blocks dirtied
blocks_written:
type: integer
description: Total blocks written
traffic_control_warnings:
type: integer
description: The number of executions that triggered a traffic control warning
traffic_control_throttled:
type: integer
description: The number of executions throttled by traffic control
traffic_control_checked:
type: integer
description: The number of executions checked by traffic control rules
required:
- id
- fingerprint
- statement_type
- keyspace
- normalized_sql
- syntax_highlighted_sql
- multishard
- query_count
- error_count
- tables
- qualified_tables
- table_keyspaces
- index_usages
- routing_index_usages
- sum_shard_queries
- max_shard_queries
- avg_shard_queries
- avg_parallel_workers
- sum_rows_read
- sum_rows_affected
- sum_rows_returned
- rows_read_per_returned
- rows_read_per_query
- rows_returned_per_query
- rows_affected_per_query
- sum_total_duration_millis
- sum_total_duration_percent
- sum_cpu_duration_millis
- sum_cpu_duration_percent
- sum_io_duration_millis
- sum_io_duration_percent
- last_run_at
- time_per_query
- p50_latency
- p99_latency
- max_latency
- egress_bytes
- egress_bytes_per_query
- max_egress_bytes
- ingress_bytes
- ingress_bytes_per_query
- max_ingress_bytes
- blocks_read
- blocks_hit
- block_cache_hit_ratio
- blocks_dirtied
- blocks_written
- traffic_control_warnings
- traffic_control_throttled
- traffic_control_checked
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PostgresSwitchover:
type: object
properties:
id:
type: string
description: The ID of the switchover
state:
type: string
enum:
- pending
- running
- succeeded
- failed
- canceled
description: The state of the switchover
method:
type: string
enum:
- switchover
- restart
description: How the primary was moved. `switchover` promotes a replica on a highly available branch; `restart` restarts the single instance of a branch that has no replicas. Absent until the operator selects one.
nullable: true
error:
type: string
description: Why the switchover failed. A failed switchover has an unconfirmed outcome and does not imply the primary stayed put.
nullable: true
started_at:
type: string
description: When the switchover was requested
nullable: true
completed_at:
type: string
description: When the switchover finished
nullable: true
created_at:
type: string
description: When the switchover was created
updated_at:
type: string
description: When the switchover was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
PaginatedPostgresSwitchover:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the switchover
state:
type: string
enum:
- pending
- running
- succeeded
- failed
- canceled
description: The state of the switchover
method:
type: string
enum:
- switchover
- restart
description: How the primary was moved. `switchover` promotes a replica on a highly available branch; `restart` restarts the single instance of a branch that has no replicas. Absent until the operator selects one.
nullable: true
error:
type: string
description: Why the switchover failed. A failed switchover has an unconfirmed outcome and does not imply the primary stayed put.
nullable: true
started_at:
type: string
description: When the switchover was requested
nullable: true
completed_at:
type: string
description: When the switchover finished
nullable: true
created_at:
type: string
description: When the switchover was created
updated_at:
type: string
description: When the switchover was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PostgresBouncer:
type: object
properties:
id:
type: string
description: The ID of the bouncer
name:
type: string
description: The name of the bouncer
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The instance type the bouncer targets
replicas_per_cell:
type: integer
description: The count of replicas in each cell
created_at:
type: string
description: When the bouncer was created
updated_at:
type: string
description: When the bouncer was updated
deleted_at:
type: string
description: When the bouncer was deleted
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
description: The namespace of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- namespace
- name
- display_name
- category
- description
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- url
- options
- actor
required:
- id
- name
- sku
- target
- replicas_per_cell
- created_at
- updated_at
- deleted_at
- actor
- branch
- parameters
PaginatedPostgresBouncer:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer
name:
type: string
description: The name of the bouncer
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The instance type the bouncer targets
replicas_per_cell:
type: integer
description: The count of replicas in each cell
created_at:
type: string
description: When the bouncer was created
updated_at:
type: string
description: When the bouncer was updated
deleted_at:
type: string
description: When the bouncer was deleted
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
description: The namespace of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- namespace
- name
- display_name
- category
- description
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- url
- options
- actor
required:
- id
- name
- sku
- target
- replicas_per_cell
- created_at
- updated_at
- deleted_at
- actor
- branch
- parameters
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PostgresBouncerResizeRequest:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer after the resize
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The backend target for the bouncer after the resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer before the resize
previous_target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The backend target for the bouncer before the resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
nullable: true
completed_at:
type: string
description: The time the bouncer resize completed
nullable: true
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
bouncer:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
required:
- id
- state
- replicas_per_cell
- target
- parameters
- previous_replicas_per_cell
- previous_target
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
PaginatedPostgresBouncerResizeRequest:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer after the resize
target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The backend target for the bouncer after the resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer before the resize
previous_target:
type: string
enum:
- primary
- replica
- replica_az_affinity
description: The backend target for the bouncer before the resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
nullable: true
completed_at:
type: string
description: The time the bouncer resize completed
nullable: true
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
bouncer:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
required:
- name
- display_name
- cpu
- ram
- sort_order
required:
- id
- state
- replicas_per_cell
- target
- parameters
- previous_replicas_per_cell
- previous_target
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedAuditLogEvent:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
has_next:
type: boolean
description: Whether there is a next page of results
has_prev:
type: boolean
description: Whether there is a previous page of results
cursor_start:
type: string
description: The ID of the first object in the current results, or null when there are no results
nullable: true
cursor_end:
type: string
description: The ID of the last object in the current results, or null when there are no results
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the audit log
actor_id:
type: string
description: The ID of the actor
nullable: true
actor_type:
type: string
description: The type of the actor. Such as 'User' or 'ServiceToken'
nullable: true
auditable_id:
type: string
description: The ID of the auditable object
nullable: true
auditable_type:
type: string
description: The type of the auditable. Such as 'Organization' or 'Database'
nullable: true
target_id:
type: string
description: The ID of the target
nullable: true
target_type:
type: string
description: The type of the target. Such as 'DatabaseBranch' or 'DatabaseBranchPassword'
nullable: true
location:
type: string
description: The location of the actor based on their IP address
nullable: true
target_display_name:
type: string
description: The name of the target
nullable: true
audit_action:
type: string
description: The action that was taken
action:
type: string
description: The action that was taken
actor_display_name:
type: string
description: The name of the actor
auditable_display_name:
type: string
description: The name of the auditable object
remote_ip:
type: string
description: The IP address of the actor
nullable: true
created_at:
type: string
description: When the audit log was created
updated_at:
type: string
description: When the audit log was last updated
metadata:
type: object
additionalProperties: true
description: Additional metadata containing details about the change
nullable: true
required:
- id
- actor_id
- actor_type
- auditable_id
- auditable_type
- target_id
- target_type
- location
- target_display_name
- audit_action
- action
- actor_display_name
- auditable_display_name
- remote_ip
- created_at
- updated_at
- metadata
required:
- type
- has_next
- has_prev
- cursor_start
- cursor_end
- data
ClusterSizeSku:
type: object
properties:
name:
type: string
description: The name of the cluster SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The number of CPUs
storage:
type: integer
description: The amount of storage in bytes
nullable: true
ram:
type: integer
description: The amount of memory in bytes
metal:
type: boolean
description: Whether or not the cluster SKU is Metal
enabled:
type: boolean
description: Whether or not the cluster SKU is enabled for the organization
provider:
type: string
description: The provider of the cluster SKU (nil, AWS or GCP)
nullable: true
default_vtgate:
type: string
description: The default vtgate size for the cluster SKU
default_vtgate_rate:
type: number
description: The default vtgate rate for the cluster SKU
nullable: true
replica_rate:
type: number
description: The replica rate for the cluster SKU
nullable: true
rate:
type: number
description: The rate for the cluster SKU
nullable: true
sort_order:
type: integer
description: The sort order of the cluster SKU
architecture:
type: string
description: The architecture of the cluster SKU (null, x86_64 or arm64)
nullable: true
development:
type: boolean
description: Whether or not the cluster SKU is a development SKU
production:
type: boolean
description: Whether or not the cluster SKU is a production SKU
required:
- name
- display_name
- cpu
- storage
- ram
- metal
- enabled
- provider
- default_vtgate
- default_vtgate_rate
- sort_order
- development
- production
PaginatedPlanetscaleRegion:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
Organization:
type: object
properties:
id:
type: string
description: The ID for the organization
name:
type: string
description: The name of the organization
billing_email:
type: string
description: The billing email of the organization
created_at:
type: string
description: When the organization was created
updated_at:
type: string
description: When the organization was last updated
plan:
type: string
description: The billing plan of the organization
valid_billing_info:
type: boolean
description: Whether or not the organization's billing information is valid
sso:
type: boolean
description: Whether or not SSO is enabled on the organization
sso_directory:
type: boolean
description: Whether or not the organization uses an SSO directory
single_tenancy:
type: boolean
description: Whether or not the organization has single tenancy enabled
managed_tenancy:
type: boolean
description: Whether or not the organization has managed tenancy enabled
has_past_due_invoices:
type: boolean
description: Whether or not the organization has past due billing invoices.
nullable: true
database_count:
type: integer
description: The number of databases in the organization
sso_portal_url:
type: string
description: The URL of the organization's SSO portal.
nullable: true
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: Whether or not the IdP provider is be responsible for managing roles in PlanetScale
invoice_budget_amount:
type: string
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: integer
description: The keyspace shard limit for the organization
has_card:
type: boolean
description: Whether or not the organization has a payment method on file
payment_info_required:
type: boolean
description: Whether or not the organization requires payment information
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- database_count
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
PaginatedOrganization:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the organization
name:
type: string
description: The name of the organization
billing_email:
type: string
description: The billing email of the organization
created_at:
type: string
description: When the organization was created
updated_at:
type: string
description: When the organization was last updated
plan:
type: string
description: The billing plan of the organization
valid_billing_info:
type: boolean
description: Whether or not the organization's billing information is valid
sso:
type: boolean
description: Whether or not SSO is enabled on the organization
sso_directory:
type: boolean
description: Whether or not the organization uses an SSO directory
single_tenancy:
type: boolean
description: Whether or not the organization has single tenancy enabled
managed_tenancy:
type: boolean
description: Whether or not the organization has managed tenancy enabled
has_past_due_invoices:
type: boolean
description: Whether or not the organization has past due billing invoices.
nullable: true
database_count:
type: integer
description: The number of databases in the organization
sso_portal_url:
type: string
description: The URL of the organization's SSO portal.
nullable: true
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: Whether or not the IdP provider is be responsible for managing roles in PlanetScale
invoice_budget_amount:
type: string
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: integer
description: The keyspace shard limit for the organization
has_card:
type: boolean
description: Whether or not the organization has a payment method on file
payment_info_required:
type: boolean
description: Whether or not the organization requires payment information
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- database_count
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
OrganizationMembership:
type: object
properties:
id:
type: string
description: The ID of the membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
required:
- id
- user
- role
- created_at
- updated_at
PaginatedOrganizationMembership:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
sso:
type: boolean
description: Whether or not the user is managed by SSO.
nullable: true
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider.
nullable: true
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory.
nullable: true
email_verified:
type: boolean
description: Whether or not the user is verified by email.
nullable: true
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
required:
- id
- user
- role
- created_at
- updated_at
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
OauthApplication:
type: object
properties:
id:
type: string
description: The ID of the app
name:
type: string
description: The name of the app
redirect_uri:
type: string
description: The redirect URI of the OAuth application
domain:
type: string
description: The domain of the OAuth application. Used for verification of a valid redirect uri
created_at:
type: string
description: When the OAuth application was created
updated_at:
type: string
description: When the OAuth application was last updated
scopes:
type: string
description: The scopes that the OAuth application requires on a user account, as a space-separated string
avatar:
type: string
description: The image source for the OAuth application's avatar
client_id:
type: string
description: The OAuth application's unique client id
tokens:
type: integer
description: The number of tokens issued by the OAuth application
dcr:
type: boolean
description: Whether the OAuth application was created via Dynamic Client Registration
single_org_authorization:
type: boolean
description: Whether the OAuth application is limited to authorizing a single organization
requires_org_scope:
type: boolean
description: Whether the OAuth application requires at least one organization to be authorized
scopes_by_resource:
type: object
additionalProperties: true
description: Scopes grouped by resource type (database, organization, branch, user) with scope, description, and admin flag
all_scopes_by_resource:
type: object
additionalProperties: true
description: All available scopes grouped by resource type with scope, description, selected, and admin flags
mcp_tool_groups:
items:
type: object
additionalProperties: true
type: array
description: MCP tool groups (id, label, section, tools, scopes, parent_id, default_enabled, roles) selectable when authorizing a DCR app; only present for DCR apps. Database-section groups also carry org_scopes (the organization-tier scope names granting the group across all databases in an organization) and org_roles (the organization roles allowed to grant them); both are null for organization-section groups
nullable: true
required:
- id
- name
- redirect_uri
- domain
- created_at
- updated_at
- scopes
- avatar
- client_id
- tokens
- dcr
- single_org_authorization
- requires_org_scope
- scopes_by_resource
- all_scopes_by_resource
PaginatedOauthApplication:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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:
type: string
description: The scopes that the OAuth application requires on a user account, as a space-separated string
avatar:
type: string
description: The image source for the OAuth application's avatar
client_id:
type: string
description: The OAuth application's unique client id
tokens:
type: integer
description: The number of tokens issued by the OAuth application
dcr:
type: boolean
description: Whether the OAuth application was created via Dynamic Client Registration
single_org_authorization:
type: boolean
description: Whether the OAuth application is limited to authorizing a single organization
requires_org_scope:
type: boolean
description: Whether the OAuth application requires at least one organization to be authorized
scopes_by_resource:
type: object
additionalProperties: true
description: Scopes grouped by resource type (database, organization, branch, user) with scope, description, and admin flag
all_scopes_by_resource:
type: object
additionalProperties: true
description: All available scopes grouped by resource type with scope, description, selected, and admin flags
mcp_tool_groups:
items:
type: object
additionalProperties: true
type: array
description: MCP tool groups (id, label, section, tools, scopes, parent_id, default_enabled, roles) selectable when authorizing a DCR app; only present for DCR apps. Database-section groups also carry org_scopes (the organization-tier scope names granting the group across all databases in an organization) and org_roles (the organization roles allowed to grant them); both are null for organization-section groups
nullable: true
required:
- id
- name
- redirect_uri
- domain
- created_at
- updated_at
- scopes
- avatar
- client_id
- tokens
- dcr
- single_org_authorization
- requires_org_scope
- scopes_by_resource
- all_scopes_by_resource
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
PaginatedBranchMaintenanceWindow:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the maintenance window
created_at:
type: string
description: When the maintenance window was created
updated_at:
type: string
description: When the maintenance window was last updated
started_at:
type: string
description: When the maintenance window started
nullable: true
finished_at:
type: string
description: When the maintenance window finished
nullable: true
required:
- id
- created_at
- updated_at
- started_at
- finished_at
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
BranchMaintenanceSchedule:
type: object
properties:
id:
type: string
description: The ID of the maintenance schedule
name:
type: string
description: The display name of the maintenance schedule
created_at:
type: string
description: When the maintenance schedule was created
updated_at:
type: string
description: When the maintenance schedule was last updated
last_window_datetime:
type: string
description: When the last maintenance window started
next_window_datetime:
type: string
description: When the next maintenance window is scheduled
duration:
type: integer
description: The duration of the maintenance window in hours
day:
type: integer
description: Day of the week (0 = Sunday, 6 = Saturday, 7 = every day)
hour:
type: integer
description: Hour of the day in UTC (0-23)
week:
type: integer
description: Week of the month for monthly schedules (0-3)
frequency_value:
type: integer
description: The frequency value of the maintenance schedule
frequency_unit:
type: string
enum:
- day
- week
- month
- once
description: The frequency unit of the maintenance schedule
enabled:
type: boolean
description: Whether the maintenance schedule is enabled
expires_at:
type: string
description: When a one-time maintenance schedule expires
nullable: true
deadline_at:
type: string
description: The deadline for a required maintenance schedule
nullable: true
required:
type: boolean
description: Whether the maintenance schedule is required
pending_vitess_version_update:
type: boolean
description: Whether there is a pending Vitess version update
pending_vitess_version:
type: string
description: The pending Vitess version, if any
nullable: true
pending_mysql_version_update:
type: boolean
description: Whether there is a pending MySQL version update
pending_mysql_version:
type: string
description: The pending MySQL version, if any
nullable: true
required:
- id
- name
- created_at
- updated_at
- last_window_datetime
- next_window_datetime
- duration
- day
- hour
- week
- frequency_value
- frequency_unit
- enabled
- expires_at
- deadline_at
- required
- pending_vitess_version_update
- pending_vitess_version
- pending_mysql_version_update
- pending_mysql_version
PaginatedBranchMaintenanceSchedule:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the maintenance schedule
name:
type: string
description: The display name of the maintenance schedule
created_at:
type: string
description: When the maintenance schedule was created
updated_at:
type: string
description: When the maintenance schedule was last updated
last_window_datetime:
type: string
description: When the last maintenance window started
next_window_datetime:
type: string
description: When the next maintenance window is scheduled
duration:
type: integer
description: The duration of the maintenance window in hours
day:
type: integer
description: Day of the week (0 = Sunday, 6 = Saturday, 7 = every day)
hour:
type: integer
description: Hour of the day in UTC (0-23)
week:
type: integer
description: Week of the month for monthly schedules (0-3)
frequency_value:
type: integer
description: The frequency value of the maintenance schedule
frequency_unit:
type: string
enum:
- day
- week
- month
- once
description: The frequency unit of the maintenance schedule
enabled:
type: boolean
description: Whether the maintenance schedule is enabled
expires_at:
type: string
description: When a one-time maintenance schedule expires
nullable: true
deadline_at:
type: string
description: The deadline for a required maintenance schedule
nullable: true
required:
type: boolean
description: Whether the maintenance schedule is required
pending_vitess_version_update:
type: boolean
description: Whether there is a pending Vitess version update
pending_vitess_version:
type: string
description: The pending Vitess version, if any
nullable: true
pending_mysql_version_update:
type: boolean
description: Whether there is a pending MySQL version update
pending_mysql_version:
type: string
description: The pending MySQL version, if any
nullable: true
required:
- id
- name
- created_at
- updated_at
- last_window_datetime
- next_window_datetime
- duration
- day
- hour
- week
- frequency_value
- frequency_unit
- enabled
- expires_at
- deadline_at
- required
- pending_vitess_version_update
- pending_vitess_version
- pending_mysql_version_update
- pending_mysql_version
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
KeyspaceResizeRequest:
type: object
properties:
id:
type: string
description: The ID of the keyspace resize request
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
- queued
description: The state of the resize request
started_at:
type: string
description: When the resize request started
nullable: true
completed_at:
type: string
description: When the resize request completed
nullable: true
created_at:
type: string
description: When the resize request was created
updated_at:
type: string
description: When the resize request was last updated
extra_replicas:
type: integer
description: The number of extra replicas requested for the keyspace
vector_pool_allocation:
type: number
description: Percentage of buffer pool memory allocated to vector indexes
previous_vector_pool_allocation:
type: number
description: Previous percentage of buffer pool memory allocated to vector indexes
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
previous_cluster_name:
type: string
description: Previous SKU representing the keyspace cluster size
previous_cluster_display_name:
type: string
description: Previous SKU representing the keyspace cluster size for display
replicas:
type: integer
description: Total number of replicas in the keyspace after resize
previous_replicas:
type: integer
description: Total number of replicas in the keyspace before resize
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- extra_replicas
- vector_pool_allocation
- previous_vector_pool_allocation
- cluster_name
- cluster_display_name
- previous_cluster_name
- previous_cluster_display_name
- replicas
- previous_replicas
- actor
PaginatedKeyspaceResizeRequest:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the keyspace resize request
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
- queued
description: The state of the resize request
started_at:
type: string
description: When the resize request started
nullable: true
completed_at:
type: string
description: When the resize request completed
nullable: true
created_at:
type: string
description: When the resize request was created
updated_at:
type: string
description: When the resize request was last updated
extra_replicas:
type: integer
description: The number of extra replicas requested for the keyspace
vector_pool_allocation:
type: number
description: Percentage of buffer pool memory allocated to vector indexes
previous_vector_pool_allocation:
type: number
description: Previous percentage of buffer pool memory allocated to vector indexes
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
previous_cluster_name:
type: string
description: Previous SKU representing the keyspace cluster size
previous_cluster_display_name:
type: string
description: Previous SKU representing the keyspace cluster size for display
replicas:
type: integer
description: Total number of replicas in the keyspace after resize
previous_replicas:
type: integer
description: Total number of replicas in the keyspace before resize
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- extra_replicas
- vector_pool_allocation
- previous_vector_pool_allocation
- cluster_name
- cluster_display_name
- previous_cluster_name
- previous_cluster_display_name
- replicas
- previous_replicas
- actor
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedDatabaseBranchReadOnlyRegion:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the read-only region
display_name:
type: string
description: The name of the read-only region
created_at:
type: string
description: When the read-only region was created
updated_at:
type: string
description: When the read-only region was last updated
ready_at:
type: string
description: When the read-only region was ready to serve queries
nullable: true
ready:
type: boolean
description: Whether or not the read-only region is ready to serve queries
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
required:
- id
- display_name
- created_at
- updated_at
- ready_at
- ready
- actor
- region
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
Database:
type: object
properties:
id:
type: string
description: The ID of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
branches_count:
type: integer
description: The total number of database branches
open_schema_recommendations_count:
type: integer
description: The total number of schema recommendations
development_branches_count:
type: integer
description: The total number of database development branches
production_branches_count:
type: integer
description: The total number of database production branches
issues_count:
type: integer
description: The total number of ongoing issues within a database
nullable: true
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: If the database has reached its backup restored branch limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
nullable: true
finished_at:
type: string
description: When the import finished
nullable: true
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
required:
- hostname
- port
- database
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: Whether an approval is required to deploy schema changes to this database
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
config_changing:
type: boolean
description: True if a config change is in progress
config_change_queued:
type: boolean
description: True if a config change is queued for maintenance window
allow_data_branching:
type: boolean
description: Whether seeding branches with data is enabled for all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: Whether to automatically manage Rails migrations during deploy requests.
nullable: true
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
prefer_instant:
type: boolean
description: Whether deploy requests default to instant deploy when it is available
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data.
nullable: true
migration_framework:
type: string
description: Framework used for applying migrations.
nullable: true
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- deletion_protected
- resizing
- resize_queued
- config_changing
- config_change_queued
- allow_data_branching
- foreign_keys_enabled
- restrict_branch_region
- prefer_instant
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- created_at
- updated_at
- schema_last_updated_at
- kind
PaginatedDatabase:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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: integer
description: The total number of database branches
open_schema_recommendations_count:
type: integer
description: The total number of schema recommendations
development_branches_count:
type: integer
description: The total number of database development branches
production_branches_count:
type: integer
description: The total number of database production branches
issues_count:
type: integer
description: The total number of ongoing issues within a database
nullable: true
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: If the database has reached its backup restored branch limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
nullable: true
finished_at:
type: string
description: When the import finished
nullable: true
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
required:
- hostname
- port
- database
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: Whether an approval is required to deploy schema changes to this database
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
config_changing:
type: boolean
description: True if a config change is in progress
config_change_queued:
type: boolean
description: True if a config change is queued for maintenance window
allow_data_branching:
type: boolean
description: Whether seeding branches with data is enabled for all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: Whether to automatically manage Rails migrations during deploy requests.
nullable: true
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
prefer_instant:
type: boolean
description: Whether deploy requests default to instant deploy when it is available
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data.
nullable: true
migration_framework:
type: string
description: Framework used for applying migrations.
nullable: true
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- deletion_protected
- resizing
- resize_queued
- config_changing
- config_change_queued
- allow_data_branching
- foreign_keys_enabled
- restrict_branch_region
- prefer_instant
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- created_at
- updated_at
- schema_last_updated_at
- kind
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
PostgresClusterCidr:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
description:
type: string
description: An optional description for the IP restriction rule
nullable: true
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- schema
- role
- cidrs
- description
- created_at
- updated_at
- deleted_at
- actor
PaginatedPostgresClusterCidr:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
description:
type: string
description: An optional description for the IP restriction rule
nullable: true
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
nullable: true
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- schema
- role
- cidrs
- description
- created_at
- updated_at
- deleted_at
- actor
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
DatabaseBranchPassword:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: The list of hosts in each availability zone providing direct access to a vtgate
ttl_seconds:
type: integer
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plaintext password. Null except in the response from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
PaginatedDatabaseBranchPassword:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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
nullable: true
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
nullable: true
expires_at:
type: string
description: When the password will expire
nullable: true
last_used_at:
type: string
description: When the password was last used to execute a query
nullable: true
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
direct_vtgate_addresses:
items:
type: string
type: array
description: The list of hosts in each availability zone providing direct access to a vtgate
ttl_seconds:
type: integer
description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed
nullable: true
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plaintext password. Null except in the response from the create endpoint.
nullable: true
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
DatabaseBranchKeyspace:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_in_progress:
type: boolean
description: True if the keyspace has an unfinished resize request
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
config_change_in_progress:
type: boolean
description: Is the keyspace undergoing a config change
ready:
type: boolean
description: Is the keyspace provisioned and serving traffic
metal:
type: boolean
description: Is the keyspace running on metal instances
default:
type: boolean
description: Is this the default keyspace for the branch
imported:
type: boolean
description: Is this keyspace used in an import
vector_pool_allocation:
type: number
description: Percentage of buffer pool memory allocated to vector indexes
nullable: true
node_ttl_strategy:
type: string
enum:
- node_ttl_follow_maintenance
- node_ttl_always
- node_ttl_off
description: Controls when node TTL drains are allowed
replication_durability_constraints:
type: object
properties:
strategy:
type: string
enum:
- available
- lag
- always
description: The replication durability strategy
nullable: true
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_in_progress
- resize_pending
- config_change_in_progress
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
PaginatedDatabaseBranchKeyspace:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_in_progress:
type: boolean
description: True if the keyspace has an unfinished resize request
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
config_change_in_progress:
type: boolean
description: Is the keyspace undergoing a config change
ready:
type: boolean
description: Is the keyspace provisioned and serving traffic
metal:
type: boolean
description: Is the keyspace running on metal instances
default:
type: boolean
description: Is this the default keyspace for the branch
imported:
type: boolean
description: Is this keyspace used in an import
vector_pool_allocation:
type: number
description: Percentage of buffer pool memory allocated to vector indexes
nullable: true
node_ttl_strategy:
type: string
enum:
- node_ttl_follow_maintenance
- node_ttl_always
- node_ttl_off
description: Controls when node TTL drains are allowed
replication_durability_constraints:
type: object
properties:
strategy:
type: string
enum:
- available
- lag
- always
description: The replication durability strategy
nullable: true
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_in_progress
- resize_pending
- config_change_in_progress
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
MysqlClusterResizeRequest:
type: object
properties:
id:
type: string
description: The ID of the branch resize request
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
- queued
description: The state of the branch resize request
started_at:
type: string
description: When the branch resize request started
nullable: true
completed_at:
type: string
description: When the branch resize request completed
nullable: true
created_at:
type: string
description: When the branch resize request was created
updated_at:
type: string
description: When the branch resize request was last updated
vtgate_size:
type: string
description: The size of the vtgate cluster
previous_vtgate_size:
type: string
description: The previous size of the vtgate cluster
vtgate_count:
type: integer
description: The number of vtgates in an availability zone
previous_vtgate_count:
type: integer
description: The previous number of vtgates in the availability zone
vtgate_max_count:
type: integer
description: The maximum number of vtgates in an availability zone when autoscaling is enabled
previous_vtgate_max_count:
type: integer
description: The previous maximum number of vtgates in the availability zone when autoscaling is enabled
vtgate_autoscaling:
type: boolean
description: If autoscaling is enabled for the vtgate cluster
previous_vtgate_autoscaling:
type: boolean
description: The previous autoscaling setting for the vtgate cluster
vtgate_target_cpu_utilization:
type: number
description: The target CPU utilization for the vtgate cluster
previous_vtgate_target_cpu_utilization:
type: number
description: The previous target CPU utilization for the vtgate cluster
vtgate_name:
type: string
description: "The SKU representing the vtgate cluster size: VTG_5, VTG_10,…"
vtgate_display_name:
type: string
description: The SKU representing the vtgate cluster size for display
previous_vtgate_name:
type: string
description: The previous SKU representing the vtgate cluster size
previous_vtgate_display_name:
type: string
description: The previous SKU representing the vtgate cluster size for display
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- vtgate_size
- previous_vtgate_size
- vtgate_count
- previous_vtgate_count
- vtgate_max_count
- previous_vtgate_max_count
- vtgate_autoscaling
- previous_vtgate_autoscaling
- vtgate_target_cpu_utilization
- previous_vtgate_target_cpu_utilization
- vtgate_name
- vtgate_display_name
- previous_vtgate_name
- previous_vtgate_display_name
- actor
PostgresClusterParameter:
type: object
properties:
id:
type: string
description: The ID of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
namespace:
type: string
enum:
- patroni
- pgconf
- pgbouncer
description: The namespace of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
extension:
type: boolean
description: Configures an extension
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- seconds
- select
- string
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- name
- display_name
- namespace
- category
- description
- extension
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- url
- options
- actor
PostgresClusterExtension:
type: object
properties:
id:
type: string
description: The ID of the extension
name:
type: string
description: The name of the extension
description:
type: string
description: The description of the extension
internal:
type: boolean
description: The internal state of the extension
loader:
type: string
enum:
- shared_preload_libraries
- session_preload_libraries
- create_extension
description: How the extension is loaded
url:
type: string
description: The URL of the extension
available:
type: boolean
description: Whether the extension is available on the current cluster image
unavailable_reason:
type: string
description: The reason the extension is unavailable (e.g., 'container_upgrade_required')
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
namespace:
type: string
enum:
- patroni
- pgconf
- pgbouncer
description: The namespace of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
extension:
type: boolean
description: Configures an extension
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- seconds
- select
- string
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- name
- display_name
- namespace
- category
- description
- extension
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- url
- options
- actor
required:
- id
- name
- description
- internal
- loader
- url
- available
- unavailable_reason
- parameters
PaginatedSchemaLintError:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
lint_error:
type: string
description: Code representing the type of error
subject_type:
type: string
enum:
- table
- vschema
- routing_rules
description: The subject for the errors
keyspace_name:
type: string
description: The keyspace of the schema with the error
table_name:
type: string
description: The table with the error
error_description:
type: string
description: A description for the error that occurred
docs_url:
type: string
description: A link to the documentation related to the error
column_name:
type: string
description: The column in a table relevant to the error
foreign_key_column_names:
items:
type: string
type: array
description: A list of invalid foreign key columns in a table
auto_increment_column_names:
items:
type: string
type: array
description: A list of invalid auto-incremented columns
charset_name:
type: string
description: The charset of the schema
engine_name:
type: string
description: The engine of the schema
vindex_name:
type: string
description: The name of the vindex for the schema
json_path:
type: string
description: The path for an invalid JSON column
check_constraint_name:
type: string
description: The name of the invalid check constraint
enum_value:
type: string
description: The name of the invalid enum value
partitioning_type:
type: string
description: The name of the invalid partitioning type
partition_name:
type: string
description: The name of the invalid partition in the schema
required:
- lint_error
- subject_type
- keyspace_name
- table_name
- error_description
- docs_url
- column_name
- foreign_key_column_names
- auto_increment_column_names
- charset_name
- engine_name
- vindex_name
- json_path
- check_constraint_name
- enum_value
- partitioning_type
- partition_name
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
DatabaseBranch:
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
nullable: true
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
nullable: true
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_name:
type: string
description: The public SKU representing the VTGate size
nullable: true
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
vtgate_autoscaling:
type: boolean
description: Whether VTGate autoscaling is enabled
vtgate_max_count:
type: integer
description: The maximum number of VTGate instances when autoscaling is enabled
nullable: true
vtgate_target_cpu_utilization:
type: integer
description: The target CPU utilization for VTGate autoscaling
nullable: true
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
nullable: true
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the branch
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
keyspace_count:
type: integer
description: The number of keyspaces in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
nullable: true
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_name
- vtgate_count
- vtgate_autoscaling
- vtgate_max_count
- vtgate_target_cpu_utilization
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- deletion_protected
- sharded
- shard_count
- keyspace_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
PaginatedDatabaseBranch:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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
nullable: true
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
nullable: true
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
nullable: true
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_name:
type: string
description: The public SKU representing the VTGate size
nullable: true
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
vtgate_autoscaling:
type: boolean
description: Whether VTGate autoscaling is enabled
vtgate_max_count:
type: integer
description: The maximum number of VTGate instances when autoscaling is enabled
nullable: true
vtgate_target_cpu_utilization:
type: integer
description: The target CPU utilization for VTGate autoscaling
nullable: true
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
nullable: true
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
deletion_protected:
type: boolean
description: Whether deletion protection is enabled for the branch
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
keyspace_count:
type: integer
description: The number of keyspaces in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
mysql_supported:
type: boolean
description: Whether the region supports MySQL/Vitess databases
postgresql_supported:
type: boolean
description: Whether the region supports PostgreSQL databases
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
- mysql_supported
- postgresql_supported
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
nullable: true
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_name
- vtgate_count
- vtgate_autoscaling
- vtgate_max_count
- vtgate_target_cpu_utilization
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- deletion_protected
- sharded
- shard_count
- keyspace_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
PaginatedMysqlClusterResizeRequest:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the branch resize request
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
- queued
description: The state of the branch resize request
started_at:
type: string
description: When the branch resize request started
nullable: true
completed_at:
type: string
description: When the branch resize request completed
nullable: true
created_at:
type: string
description: When the branch resize request was created
updated_at:
type: string
description: When the branch resize request was last updated
vtgate_size:
type: string
description: The size of the vtgate cluster
previous_vtgate_size:
type: string
description: The previous size of the vtgate cluster
vtgate_count:
type: integer
description: The number of vtgates in an availability zone
previous_vtgate_count:
type: integer
description: The previous number of vtgates in the availability zone
vtgate_max_count:
type: integer
description: The maximum number of vtgates in an availability zone when autoscaling is enabled
previous_vtgate_max_count:
type: integer
description: The previous maximum number of vtgates in the availability zone when autoscaling is enabled
vtgate_autoscaling:
type: boolean
description: If autoscaling is enabled for the vtgate cluster
previous_vtgate_autoscaling:
type: boolean
description: The previous autoscaling setting for the vtgate cluster
vtgate_target_cpu_utilization:
type: number
description: The target CPU utilization for the vtgate cluster
previous_vtgate_target_cpu_utilization:
type: number
description: The previous target CPU utilization for the vtgate cluster
vtgate_name:
type: string
description: "The SKU representing the vtgate cluster size: VTG_5, VTG_10,…"
vtgate_display_name:
type: string
description: The SKU representing the vtgate cluster size for display
previous_vtgate_name:
type: string
description: The previous SKU representing the vtgate cluster size
previous_vtgate_display_name:
type: string
description: The previous SKU representing the vtgate cluster size for display
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- vtgate_size
- previous_vtgate_size
- vtgate_count
- previous_vtgate_count
- vtgate_max_count
- previous_vtgate_max_count
- vtgate_autoscaling
- previous_vtgate_autoscaling
- vtgate_target_cpu_utilization
- previous_vtgate_target_cpu_utilization
- vtgate_name
- vtgate_display_name
- previous_vtgate_name
- previous_vtgate_display_name
- actor
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PostgresClusterResizeRequest:
type: object
properties:
id:
type: string
description: The ID of the branch change request
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
nullable: true
completed_at:
type: string
description: The time the branch change request completed
nullable: true
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
version:
type: string
description: The PostgreSQL version after the change
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: The previous SKU representing the branch cluster for display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_version:
type: string
description: The PostgreSQL version before the change
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: Whether storage shrinking is enabled when autoscaling is enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
- hyperdisk_balanced
- premium_v2_lrs
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
confirm_shrink:
type: boolean
description: Whether the change re-applies the current minimum disk size to shrink the provisioned disk
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- version
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_version
- 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
- confirm_shrink
PaginatedPostgresClusterResizeRequest:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the branch change request
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
nullable: true
completed_at:
type: string
description: The time the branch change request completed
nullable: true
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
version:
type: string
description: The PostgreSQL version after the change
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: The previous SKU representing the branch cluster for display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_version:
type: string
description: The PostgreSQL version before the change
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: Whether storage shrinking is enabled when autoscaling is enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
- hyperdisk_balanced
- premium_v2_lrs
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
confirm_shrink:
type: boolean
description: Whether the change re-applies the current minimum disk size to shrink the provisioned disk
required:
- id
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- version
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_version
- 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
- confirm_shrink
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
Backup:
type: object
properties:
id:
type: string
description: The ID of the backup
name:
type: string
description: The name of the backup
state:
type: string
enum:
- pending
- running
- success
- failed
- canceled
- ignored
description: The current state of the backup
size:
type: integer
description: The size of the backup in bytes
estimated_storage_cost:
type: number
description: The estimated storage cost of the backup
created_at:
type: string
description: When the backup was created
updated_at:
type: string
description: When the backup was last updated
started_at:
type: string
description: When the backup started
nullable: true
expires_at:
type: string
description: When the backup expires
nullable: true
completed_at:
type: string
description: When the backup completed
nullable: true
deleted_at:
type: string
description: When the backup was deleted
nullable: true
pvc_size:
type: integer
description: Size of the PVC used for the backup
uncompressed_size:
type: integer
description: The uncompressed (logical) size of the backup in bytes
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
nullable: true
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
nullable: true
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
nullable: true
database_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- uncompressed_size
- protected
- required
- restored_branches
- actor
PaginatedBackup:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
total_count:
type: integer
description: The total number of matching results
total_pages:
type: integer
description: The total number of pages of matching 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: integer
description: The size of the backup in bytes
estimated_storage_cost:
type: number
description: The estimated storage cost of the backup
created_at:
type: string
description: When the backup was created
updated_at:
type: string
description: When the backup was last updated
started_at:
type: string
description: When the backup started
nullable: true
expires_at:
type: string
description: When the backup expires
nullable: true
completed_at:
type: string
description: When the backup completed
nullable: true
deleted_at:
type: string
description: When the backup was deleted
nullable: true
pvc_size:
type: integer
description: Size of the PVC used for the backup
uncompressed_size:
type: integer
description: The uncompressed (logical) size of the backup in bytes
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
required:
- id
- display_name
- avatar_url
nullable: true
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
nullable: true
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
nullable: true
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
nullable: true
database_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
nullable: true
required:
- id
- name
- created_at
- updated_at
- deleted_at
nullable: true
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- uncompressed_size
- protected
- required
- restored_branches
- actor
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- total_count
- total_pages
- data
BackupPolicy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
PaginatedBackupPolicy:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the backup policy
display_name:
type: string
description: The display name of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: integer
description: A number value for the retention period of the backup policy
retention_unit:
type: string
description: The unit for the retention period of the backup policy
frequency_value:
type: integer
description: A number value for the frequency of the backup policy
frequency_unit:
type: string
description: The unit for the frequency of the backup policy
schedule_time:
type: string
description: The time of day that the backup is scheduled, in HH:MM format
schedule_day:
type: integer
description: Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday
nullable: true
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
nullable: true
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
nullable: true
next_run_at:
type: string
description: When the backup will next run
nullable: true
required:
type: boolean
description: Whether the policy is a required system backup
required:
- id
- display_name
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
Anomaly:
type: object
properties:
id:
type: string
description: The ID of the anomaly
period_start:
type: string
description: When the anomaly started
period_end:
type: string
description: When the anomaly ended
minutes_in_violation:
type: integer
description: The number of minutes query latency was in violation of the expected baseline
active:
type: boolean
description: Whether the anomaly is ongoing
duration:
type: number
description: The duration of the anomaly in seconds
metrics_start:
type: string
description: Start of the metrics window surrounding the anomaly
metrics_end:
type: string
description: End of the metrics window surrounding the anomaly
correlations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the correlation
r:
type: number
description: The correlation coefficient between the query and the anomaly
keyspace:
type: string
description: The keyspace the query ran against
fingerprint:
type: string
description: The query fingerprint
normalized_sql:
type: string
description: The normalized SQL statement
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL statement
tablet_type:
type: string
enum:
- primary
- replica
- rdonly
description: The tablet type the query ran against
required:
- id
- r
- keyspace
- fingerprint
- normalized_sql
- syntax_highlighted_sql
- tablet_type
nullable: true
required:
- id
- period_start
- period_end
- minutes_in_violation
- active
- duration
- metrics_start
- metrics_end
PaginatedAnomaly:
type: object
properties:
type:
type: string
description: The response type. Always "list" for paginated responses.
current_page:
type: integer
description: The current page number
per_page:
type: integer
description: The maximum number of results per page
next_page:
type: integer
description: The next page number, or null when this is the last page
nullable: true
next_page_url:
type: string
description: The next page of results, or null when this is the last page
nullable: true
prev_page:
type: integer
description: The previous page number, or null when this is the first page
nullable: true
prev_page_url:
type: string
description: The previous page of results, or null when this is the first page
nullable: true
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the anomaly
period_start:
type: string
description: When the anomaly started
period_end:
type: string
description: When the anomaly ended
minutes_in_violation:
type: integer
description: The number of minutes query latency was in violation of the expected baseline
active:
type: boolean
description: Whether the anomaly is ongoing
duration:
type: number
description: The duration of the anomaly in seconds
metrics_start:
type: string
description: Start of the metrics window surrounding the anomaly
metrics_end:
type: string
description: End of the metrics window surrounding the anomaly
correlations:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the correlation
r:
type: number
description: The correlation coefficient between the query and the anomaly
keyspace:
type: string
description: The keyspace the query ran against
fingerprint:
type: string
description: The query fingerprint
normalized_sql:
type: string
description: The normalized SQL statement
syntax_highlighted_sql:
type: string
description: Syntax highlighted SQL statement
tablet_type:
type: string
enum:
- primary
- replica
- rdonly
description: The tablet type the query ran against
required:
- id
- r
- keyspace
- fingerprint
- normalized_sql
- syntax_highlighted_sql
- tablet_type
nullable: true
required:
- id
- period_start
- period_end
- minutes_in_violation
- active
- duration
- metrics_start
- metrics_end
required:
- type
- current_page
- per_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data