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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the organization
name:
type: string
description: The name of the organization
billing_email:
type: string
description: The billing email of the organization
created_at:
type: string
description: When the organization was created
updated_at:
type: string
description: When the organization was last updated
plan:
type: string
description: The billing plan of the organization
valid_billing_info:
type: boolean
description: Whether or not the organization's billing information is valid
sso:
type: boolean
description: Whether or not SSO is enabled on the organization
sso_directory:
type: boolean
description: Whether or not the organization uses an SSO directory
single_tenancy:
type: boolean
description: Whether or not the organization has single tenancy enabled
managed_tenancy:
type: boolean
description: Whether or not the organization has managed tenancy enabled
has_past_due_invoices:
type: boolean
description: Whether or not the organization has past due billing invoices
database_count:
type: integer
description: The number of databases in the organization
sso_portal_url:
type: string
description: The URL of the organization's SSO portal
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: Whether or not the IdP provider is be responsible for managing roles in PlanetScale
invoice_budget_amount:
type: number
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: 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
additionalProperties: false
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- has_past_due_invoices
- database_count
- sso_portal_url
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
When using a service token, returns the list of organizations the service token has access to. When using an OAuth token, returns the list of organizations the user has access to.
### Authorization
A OAuth token must have at least one of the following scopes in order to use this API endpoint:
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| User | `read_organizations` |
/organizations/{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
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
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: Whether or not the IdP provider is be responsible for managing roles in PlanetScale
invoice_budget_amount:
type: number
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: 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
additionalProperties: false
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- has_past_due_invoices
- database_count
- sso_portal_url
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| User | `read_organizations` |
| Organization | `read_organization` |
patch:
tags:
- Organizations
operationId: update_organization
summary: Update an organization
parameters:
- name: 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
additionalProperties: false
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
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
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: Whether or not the IdP provider is be responsible for managing roles in PlanetScale
invoice_budget_amount:
type: number
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: 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
additionalProperties: false
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- has_past_due_invoices
- database_count
- sso_portal_url
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A 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
responses:
"200":
description: Returns the audit log events
headers: {}
content:
application/json:
schema:
type: object
properties:
has_next:
type: boolean
description: Whether there is a next page of results
has_prev:
type: boolean
description: Whether there is a previous page of results
cursor_start:
type: string
description: The ID of the first object in the current results
cursor_end:
type: string
description: The ID of the last object in the current results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the audit log
actor_id:
type: string
description: The ID of the actor
actor_type:
type: string
description: The type of the actor. Such as 'User' or 'ServiceToken'
auditable_id:
type: string
description: The ID of the auditable object
auditable_type:
type: string
description: The type of the auditable. Such as 'Organization' or 'Database'
target_id:
type: string
description: The ID of the target
target_type:
type: string
description: The type of the target. Such as 'DatabaseBranch' or 'DatabaseBranchPassword'
location:
type: string
description: The location of the actor based on their IP address
target_display_name:
type: string
description: The name of the target
audit_action:
type: string
description: The action that was taken
action:
type: string
description: The action that was taken
actor_display_name:
type: string
description: The name of the actor
auditable_display_name:
type: string
description: The name of the auditable object
remote_ip:
type: string
description: The IP address of the actor
created_at:
type: string
description: When the audit log was created
updated_at:
type: string
description: When the audit log was last updated
metadata:
type: object
additionalProperties: true
description: Additional metadata containing details about the change
additionalProperties: false
required:
- id
- actor_id
- actor_type
- auditable_id
- auditable_type
- target_id
- target_type
- location
- target_display_name
- audit_action
- action
- actor_display_name
- auditable_display_name
- remote_ip
- created_at
- updated_at
- metadata
additionalProperties: false
required:
- has_next
- has_prev
- cursor_start
- cursor_end
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_audit_logs`
/organizations/{organization}/cluster-size-skus:
get:
tags:
- Organizations
operationId: list_cluster_size_skus
summary: List available cluster sizes
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: engine
in: query
description: The database engine to filter by. Defaults to 'mysql'.
schema:
type: string
enum:
- mysql
- postgresql
- name: rates
in: query
description: Whether to include pricing rates in the response. Defaults to false.
schema:
type: boolean
- name: region
in: query
description: The region slug to get rates for. If not specified, uses the organization's default region.
schema:
type: string
responses:
"200":
description: Returns available cluster sizes with optional pricing rates
headers: {}
content:
application/json:
schema:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the cluster SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The number of CPUs
storage:
type: integer
description: The amount of storage in bytes
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)
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
replica_rate:
type: number
description: The replica rate for the cluster SKU
rate:
type: number
description: The rate for the cluster SKU
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)
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
additionalProperties: false
required:
- name
- display_name
- cpu
- storage
- ram
- metal
- enabled
- provider
- default_vtgate
- default_vtgate_rate
- sort_order
- architecture
- 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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
branches_count:
type: 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
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: If the database has reached its backup restored branch limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
finished_at:
type: string
description: When the import finished
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
additionalProperties: false
required:
- hostname
- port
- database
additionalProperties: false
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: Whether an approval is required to deploy schema changes to this database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
allow_data_branching:
type: boolean
description: Whether seeding branches with data is enabled for all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: Whether to automatically manage Rails migrations during deploy requests
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data
migration_framework:
type: string
description: Framework used for applying migrations
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
additionalProperties: false
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- issues_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- data_import
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- resizing
- resize_queued
- allow_data_branching
- foreign_keys_enabled
- automatic_migrations
- restrict_branch_region
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- migration_table_name
- migration_framework
- created_at
- updated_at
- schema_last_updated_at
- kind
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`, `delete_database`, `write_database`, `read_branch`, `delete_branch`, `create_branch`, `delete_production_branch`, `connect_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `delete_branch_password`, `delete_production_branch_password`, `delete_production_read_only_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_comment`, `create_comment`, `restore_backup`, `restore_production_branch_backup`, `read_backups`, `write_backups`, `delete_backups`, `delete_production_branch_backups`, `write_branch_vschema`, `write_production_branch_vschema`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
post:
tags:
- Databases
operationId: create_database
summary: Create a database
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the database
region:
type: string
description: The region the database will be deployed in. If left blank, defaults to the organization's default region.
cluster_size:
type: string
description: The database cluster size name (e.g., 'PS_10', 'PS_80'). Use the 'List available cluster sizes' endpoint to get available options for your organization. /v1/organizations/:organization/cluster-size-skus
replicas:
type: integer
description: The number of replicas for the database. 0 for non-HA, 2+ for HA.
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database to create.
major_version:
type: string
description: For PostgreSQL databases, the PostgreSQL major version to use for the database. Defaults to the latest available major version.
additionalProperties: false
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
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: If the database has reached its backup restored branch limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
finished_at:
type: string
description: When the import finished
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
additionalProperties: false
required:
- hostname
- port
- database
additionalProperties: false
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: Whether an approval is required to deploy schema changes to this database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
allow_data_branching:
type: boolean
description: Whether seeding branches with data is enabled for all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: Whether to automatically manage Rails migrations during deploy requests
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data
migration_framework:
type: string
description: Framework used for applying migrations
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
additionalProperties: false
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- issues_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- data_import
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- resizing
- resize_queued
- allow_data_branching
- foreign_keys_enabled
- automatic_migrations
- restrict_branch_region
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- migration_table_name
- migration_framework
- created_at
- updated_at
- schema_last_updated_at
- kind
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`create_databases`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `create_databases` |
/organizations/{organization}/databases/{database}:
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
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: If the database has reached its backup restored branch limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
finished_at:
type: string
description: When the import finished
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
additionalProperties: false
required:
- hostname
- port
- database
additionalProperties: false
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: Whether an approval is required to deploy schema changes to this database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
allow_data_branching:
type: boolean
description: Whether seeding branches with data is enabled for all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: Whether to automatically manage Rails migrations during deploy requests
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data
migration_framework:
type: string
description: Framework used for applying migrations
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
additionalProperties: false
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- issues_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- data_import
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- resizing
- resize_queued
- allow_data_branching
- foreign_keys_enabled
- automatic_migrations
- restrict_branch_region
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- migration_table_name
- migration_framework
- created_at
- updated_at
- schema_last_updated_at
- kind
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`, `delete_database`, `write_database`, `read_branch`, `delete_branch`, `create_branch`, `delete_production_branch`, `connect_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `delete_branch_password`, `delete_production_branch_password`, `delete_production_read_only_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_comment`, `create_comment`, `restore_backup`, `restore_production_branch_backup`, `read_backups`, `write_backups`, `delete_backups`, `delete_production_branch_backups`, `write_branch_vschema`, `write_production_branch_vschema`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
patch:
tags:
- Databases
operationId: update_database_settings
summary: Update database settings
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
new_name:
type: string
description: The name to update the database to
automatic_migrations:
type: boolean
description: Whether or not to copy migration data to new branches and in deploy requests. (Vitess only)
migration_framework:
type: string
description: A migration framework to use on the database. (Vitess only)
migration_table_name:
type: string
description: Name of table to use as migration table for the database. (Vitess only)
require_approval_for_deploy:
type: boolean
description: Whether or not deploy requests must be approved by a database administrator other than the request creator
restrict_branch_region:
type: boolean
description: Whether or not to limit branch creation to the same region as the one selected during database creation.
allow_data_branching:
type: boolean
description: Whether or not data branching is allowed on the database. (Vitess only)
allow_foreign_key_constraints:
type: boolean
description: Whether or not foreign key constraints are allowed on the database. (Vitess only)
insights_raw_queries:
type: boolean
description: Whether or not full queries should be collected from the database
production_branch_web_console:
type: boolean
description: Whether or not the web console can be used on the production branch of the database
default_branch:
type: string
description: The default branch of the database
additionalProperties: false
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
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: If the database has reached its backup restored branch limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
finished_at:
type: string
description: When the import finished
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
additionalProperties: false
required:
- hostname
- port
- database
additionalProperties: false
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: Whether an approval is required to deploy schema changes to this database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
allow_data_branching:
type: boolean
description: Whether seeding branches with data is enabled for all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: Whether to automatically manage Rails migrations during deploy requests
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data
migration_framework:
type: string
description: Framework used for applying migrations
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
additionalProperties: false
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- issues_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- data_import
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- resizing
- resize_queued
- allow_data_branching
- foreign_keys_enabled
- automatic_migrations
- restrict_branch_region
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- migration_table_name
- migration_framework
- created_at
- updated_at
- schema_last_updated_at
- kind
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`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}/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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_count
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- sharded
- shard_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
post:
tags:
- Database branches
operationId: create_branch
summary: Create a branch
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the branch to create
parent_branch:
type: string
description: The name of the parent branch. Defaults to the database's default branch if not provided.
backup_id:
type: string
description: If provided, restores the backup's schema and data to the new branch. Must have `restore_production_branch_backup(s)` or `restore_backup(s)` access to do this.
region:
type: string
description: The region to create the branch in. If not provided, the branch will be created in the default region for its database.
restore_point:
type: string
description: Restore from a point-in-time recovery timestamp (e.g. 2023-01-01T00:00:00Z). Available only for PostgreSQL databases.
seed_data:
type: string
enum:
- last_successful_backup
description: If provided, restores the last successful backup's schema and data to the new branch. Must have `restore_production_branch_backup(s)` or `restore_backup(s)` access to do this, in addition to Data Branching™ being enabled for the branch.
cluster_size:
type: string
description: "The database cluster size. Required if a backup_id is provided, optional otherwise. Options: PS_10, PS_20, PS_40, ..., PS_2800"
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.
additionalProperties: false
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
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_count
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- sharded
- shard_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- 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
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_count
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- sharded
- shard_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- 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
additionalProperties: false
required:
- new_name
responses:
"200":
description: Returns the updated branch
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_count
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- sharded
- shard_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_branches` |
| Database | `write_branches` |
| Branch | `write_branch` |
delete:
tags:
- Database branches
operationId: delete_branch
summary: Delete a branch
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the backup
name:
type: string
description: The name of the backup
state:
type: string
enum:
- pending
- running
- success
- failed
- canceled
- ignored
description: The current state of the backup
size:
type: 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
expires_at:
type: string
description: When the backup expires
completed_at:
type: string
description: When the backup completed
deleted_at:
type: string
description: When the backup was deleted
pvc_size:
type: integer
description: Size of the PVC used for the backup
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: 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
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
next_run_at:
type: string
description: When the backup will next run
required:
type: boolean
description: Whether the policy is a required system backup
additionalProperties: false
required:
- id
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
database_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- protected
- required
- restored_branches
- actor
- backup_policy
- schema_snapshot
- database_branch
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_backups` |
| Database | `read_backups` |
| Branch | `read_backups` |
post:
tags:
- Backups
operationId: create_backup
summary: Create a backup
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name for the backup
retention_unit:
type: string
enum:
- hour
- day
- week
- month
- year
description: Unit for the retention period of the backup
retention_value:
type: 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.
additionalProperties: false
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
expires_at:
type: string
description: When the backup expires
completed_at:
type: string
description: When the backup completed
deleted_at:
type: string
description: When the backup was deleted
pvc_size:
type: integer
description: Size of the PVC used for the backup
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: 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
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
next_run_at:
type: string
description: When the backup will next run
required:
type: boolean
description: Whether the policy is a required system backup
additionalProperties: false
required:
- id
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
database_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- protected
- required
- restored_branches
- actor
- backup_policy
- schema_snapshot
- database_branch
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_backups` |
| Database | `write_backups` |
| Branch | `write_backups` |
/organizations/{organization}/databases/{database}/branches/{branch}/backups/{id}:
get:
tags:
- Backups
operationId: get_backup
summary: Get a backup
parameters:
- name: id
in: path
required: true
description: The ID for the backup
schema:
type: string
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
"200":
description: Returns a database branch backup
headers: {}
content:
application/json:
schema:
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
expires_at:
type: string
description: When the backup expires
completed_at:
type: string
description: When the backup completed
deleted_at:
type: string
description: When the backup was deleted
pvc_size:
type: integer
description: Size of the PVC used for the backup
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: 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
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
next_run_at:
type: string
description: When the backup will next run
required:
type: boolean
description: Whether the policy is a required system backup
additionalProperties: false
required:
- id
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
database_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- protected
- required
- restored_branches
- actor
- backup_policy
- schema_snapshot
- database_branch
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_backups` |
| Database | `read_backups` |
| Branch | `read_backups` |
patch:
tags:
- Backups
operationId: update_backup
summary: Update a backup
parameters:
- name: id
in: path
required: true
description: The ID of the backup
schema:
type: string
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
protected:
type: boolean
description: Whether the backup is protected from deletion or not
additionalProperties: false
responses:
"200":
description: Returns the backup
headers: {}
content:
application/json:
schema:
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
expires_at:
type: string
description: When the backup expires
completed_at:
type: string
description: When the backup completed
deleted_at:
type: string
description: When the backup was deleted
pvc_size:
type: integer
description: Size of the PVC used for the backup
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: 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
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
next_run_at:
type: string
description: When the backup will next run
required:
type: boolean
description: Whether the policy is a required system backup
additionalProperties: false
required:
- id
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
database_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- protected
- required
- restored_branches
- actor
- backup_policy
- schema_snapshot
- database_branch
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_backups`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_backups` |
| Database | `write_backups` |
| Branch | `write_backups` |
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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer after the resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer before the resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
completed_at:
type: string
description: The time the bouncer resize completed
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
bouncer:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
additionalProperties: false
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
additionalProperties: false
required:
- name
- display_name
- cpu
- ram
- sort_order
additionalProperties: false
required:
- id
- state
- replicas_per_cell
- parameters
- previous_replicas_per_cell
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/bouncers:
get:
tags:
- Bouncers
operationId: list_bouncers
summary: List bouncers
parameters:
- name: organization
in: path
required: true
description: "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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer
name:
type: string
description: The name of the bouncer
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
additionalProperties: false
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
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
description: The namespace of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- namespace
- name
- display_name
- category
- description
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
additionalProperties: false
required:
- id
- name
- sku
- target
- replicas_per_cell
- created_at
- updated_at
- deleted_at
- actor
- branch
- parameters
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
post:
tags:
- Bouncers
operationId: create_bouncer
summary: Create a bouncer
parameters:
- name: organization
in: path
required: true
description: "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
additionalProperties: false
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
additionalProperties: false
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
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
description: The namespace of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- namespace
- name
- display_name
- category
- description
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
additionalProperties: false
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
additionalProperties: false
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
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
description: The namespace of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- namespace
- name
- display_name
- category
- description
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
additionalProperties: false
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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer after the resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer before the resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
completed_at:
type: string
description: The time the bouncer resize completed
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
bouncer:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
additionalProperties: false
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
additionalProperties: false
required:
- name
- display_name
- cpu
- ram
- sort_order
additionalProperties: false
required:
- id
- state
- replicas_per_cell
- parameters
- previous_replicas_per_cell
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
patch:
tags:
- Bouncer resizes
operationId: update_bouncer_resize_request
summary: Upsert a bouncer resize request
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: bouncer
in: path
required: true
description: The name of the bouncer
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
bouncer_size:
type: string
description: The bouncer size SKU name (e.g., 'PGB_5', 'PGB_10', 'PGB_20', 'PGB_40', 'PGB_80', 'PGB_160'). Defaults to 'PGB_5'.
replicas_per_cell:
type: integer
description: The number of PgBouncers per availability zone. Defaults to 1.
parameters:
type: object
additionalProperties: true
description: "Bouncer configuration parameters nested by namespace (e.g., {\"pgbouncer\": {\"default_pool_size\": \"100\"}}). Use the 'List cluster parameters' endpoint to retrieve available parameters. Only parameters with namespace 'pgbouncer' can be updated."
additionalProperties: false
responses:
"200":
description: Returns bouncer resize request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer after the resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer before the resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
completed_at:
type: string
description: The time the bouncer resize completed
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
bouncer:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
additionalProperties: false
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
additionalProperties: false
required:
- name
- display_name
- cpu
- ram
- sort_order
additionalProperties: false
required:
- id
- state
- replicas_per_cell
- parameters
- previous_replicas_per_cell
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
delete:
tags:
- Bouncer resizes
operationId: cancel_bouncer_resize_request
summary: Cancel a resize request
parameters:
- name: organization
in: path
required: true
description: "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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the branch change request
restart:
items:
type: integer
type: array
description: The ports requiring a restart when changes are applied
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
completed_at:
type: string
description: The time the branch change request completed
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: The previous SKU representing the branch cluster for display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: Whether storage shrinking is enabled when autoscaling is enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
additionalProperties: false
required:
- id
- restart
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_parameters
- minimum_storage_bytes
- maximum_storage_bytes
- storage_autoscaling
- storage_shrinking
- storage_type
- storage_iops
- storage_throughput_mibs
- previous_minimum_storage_bytes
- previous_maximum_storage_bytes
- previous_storage_autoscaling
- previous_storage_shrinking
- previous_storage_type
- previous_storage_iops
- previous_storage_throughput_mibs
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
patch:
tags:
- Branch changes
operationId: update_branch_change_request
summary: Upsert a change request
parameters:
- name: organization
in: path
required: true
description: "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'."
additionalProperties: false
responses:
"200":
description: Returns the branch change request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch change request
restart:
items:
type: integer
type: array
description: The ports requiring a restart when changes are applied
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
completed_at:
type: string
description: The time the branch change request completed
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: The previous SKU representing the branch cluster for display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: Whether storage shrinking is enabled when autoscaling is enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
additionalProperties: false
required:
- id
- restart
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_parameters
- minimum_storage_bytes
- maximum_storage_bytes
- storage_autoscaling
- storage_shrinking
- storage_type
- storage_iops
- storage_throughput_mibs
- previous_minimum_storage_bytes
- previous_maximum_storage_bytes
- previous_storage_autoscaling
- previous_storage_shrinking
- previous_storage_type
- previous_storage_iops
- previous_storage_throughput_mibs
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/changes/{id}:
get:
tags:
- Branch changes
operationId: get_branch_change_request
summary: Get a branch change request
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the change request
schema:
type: string
responses:
"200":
description: Returns a branch change request
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch change request
restart:
items:
type: integer
type: array
description: The ports requiring a restart when changes are applied
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
completed_at:
type: string
description: The time the branch change request completed
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: The previous SKU representing the branch cluster for display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: Whether storage shrinking is enabled when autoscaling is enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
additionalProperties: false
required:
- id
- restart
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_parameters
- minimum_storage_bytes
- maximum_storage_bytes
- storage_autoscaling
- storage_shrinking
- storage_type
- storage_iops
- storage_throughput_mibs
- previous_minimum_storage_bytes
- previous_maximum_storage_bytes
- previous_storage_autoscaling
- previous_storage_shrinking
- previous_storage_type
- previous_storage_iops
- previous_storage_throughput_mibs
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`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,…"
additionalProperties: false
required:
- cluster_size
responses:
"204":
description: Returns an empty response body
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`write_database`
/organizations/{organization}/databases/{database}/branches/{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
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_count
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- sharded
- shard_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Demotes a branch from production to development
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`connect_production_branch`, `demote_branches`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `demote_branches` |
| Database | `demote_branches` |
/organizations/{organization}/databases/{database}/branches/{branch}/extensions:
get:
tags:
- Cluster extensions
operationId: list_extensions
summary: List cluster extensions
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
responses:
"200":
description: Returns cluster extensions
headers: {}
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the extension
name:
type: string
description: The name of the extension
description:
type: string
description: The description of the extension
internal:
type: boolean
description: The internal state of the extension
shared_preload_allowed:
type: boolean
description: Whether the extension can be added to shared_preload_libraries
url:
type: string
description: The URL of the extension
available:
type: boolean
description: Whether the extension is available on the current cluster image
unavailable_reason:
type: string
description: The reason the extension is unavailable (e.g., 'container_upgrade_required')
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
namespace:
type: string
enum:
- patroni
- pgconf
- pgbouncer
description: The namespace of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
extension:
type: boolean
description: Configures an extension
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- seconds
- select
- string
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- name
- display_name
- namespace
- category
- description
- extension
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
additionalProperties: false
required:
- id
- name
- description
- internal
- shared_preload_allowed
- url
- available
- unavailable_reason
- parameters
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/keyspaces:
get:
tags:
- Database branch keyspaces
operationId: list_keyspaces
summary: Get keyspaces
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns keyspaces
headers: {}
content:
application/json:
schema:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
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
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
additionalProperties: false
required:
- strategy
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
additionalProperties: false
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
additionalProperties: false
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_pending
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_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"
additionalProperties: false
required:
- name
- cluster_size
responses:
"200":
description: Returns a created keyspace
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
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
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
additionalProperties: false
required:
- strategy
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
additionalProperties: false
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
additionalProperties: false
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_pending
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`create_branch`
/organizations/{organization}/databases/{database}/branches/{branch}/keyspaces/{keyspace}:
get:
tags:
- Database branch keyspaces
operationId: get_keyspace
summary: Get a keyspace
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
"200":
description: Returns information about a keyspace
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
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
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
additionalProperties: false
required:
- strategy
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
additionalProperties: false
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
additionalProperties: false
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_pending
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
patch:
tags:
- Database branch keyspaces
operationId: update_keyspace
summary: Configure keyspace settings
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
"200":
description: Returns the keyspace
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
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
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
additionalProperties: false
required:
- strategy
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
additionalProperties: false
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
additionalProperties: false
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_pending
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`create_branch`
delete:
tags:
- Database branch keyspaces
operationId: delete_keyspace
summary: Delete a keyspace
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
"204":
description: Delete a keyspace
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`delete_branch`, `delete_production_branch`
/organizations/{organization}/databases/{database}/branches/{branch}/keyspaces/{keyspace}/rollout-status:
get:
tags:
- Database branch keyspaces
operationId: get_keyspace_rollout_status
summary: Get keyspace rollout status
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
responses:
"200":
description: Returns information about a keyspace's rollout
headers: {}
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the keyspace
state:
type: string
description: The current state of the rollout at the keyspace level
shards:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the shard
last_rollout_started_at:
type: string
description: The time at which the rollout started
last_rollout_finished_at:
type: string
description: The time at which the rollout completed
state:
type: string
description: The current state of the rollout at the shard level
additionalProperties: false
required:
- name
- last_rollout_started_at
- last_rollout_finished_at
- state
additionalProperties: false
required:
- name
- state
- shards
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### 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
additionalProperties: false
required:
- raw
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
patch:
tags:
- Keyspace VSchemas
operationId: update_keyspace_vschema
summary: Update the VSchema for the keyspace
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: keyspace
in: path
required: true
description: The name of the keyspace
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
vschema:
type: string
description: The new VSchema for the keyspace
additionalProperties: false
required:
- vschema
responses:
"200":
description: Returns the VSchema for the keyspace
headers: {}
content:
application/json:
schema:
type: object
properties:
raw:
type: string
description: The keyspace's VSchema
additionalProperties: false
required:
- raw
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Content
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`write_production_branch_vschema`, `write_branch_vschema`
/organizations/{organization}/databases/{database}/branches/{branch}/parameters:
get:
tags:
- Cluster parameters
operationId: list_parameters
summary: List cluster parameters
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
responses:
"200":
description: Returns cluster parameters
headers: {}
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
namespace:
type: string
enum:
- patroni
- pgconf
- pgbouncer
description: The namespace of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
extension:
type: boolean
description: Configures an extension
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- seconds
- select
- string
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- name
- display_name
- namespace
- category
- description
- extension
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |2-
Returns the parameters for a branch. To update the parameters, use the "Upsert a change request" endpoint.
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/passwords:
get:
tags:
- Database branch passwords
operationId: list_passwords
summary: List passwords
parameters:
- name: organization
in: path
required: true
description: The name of the organization the password belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the password belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch the password belongs to
schema:
type: string
- name: read_only_region_id
in: query
description: A read-only region of the database branch. If present, the password results will be filtered to only those in the region
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns passwords for the branch
headers: {}
content:
application/json:
schema:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
expires_at:
type: string
description: When the password will expire
last_used_at:
type: string
description: When the password was last used to execute a query
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
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
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plain text password, available only after create
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
additionalProperties: false
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
additionalProperties: false
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- 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
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_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
additionalProperties: false
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
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
expires_at:
type: string
description: When the password will expire
last_used_at:
type: string
description: When the password was last used to execute a query
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
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
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plain text password, available only after create
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
additionalProperties: false
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
additionalProperties: false
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- 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
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
expires_at:
type: string
description: When the password will expire
last_used_at:
type: string
description: When the password was last used to execute a query
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
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
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plain text password, available only after create
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
additionalProperties: false
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
additionalProperties: false
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- 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
additionalProperties: false
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
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
expires_at:
type: string
description: When the password will expire
last_used_at:
type: string
description: When the password was last used to execute a query
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
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
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plain text password, available only after create
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
additionalProperties: false
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
additionalProperties: false
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- 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
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
expires_at:
type: string
description: When the password will expire
last_used_at:
type: string
description: When the password was last used to execute a query
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
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
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plain text password, available only after create
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
additionalProperties: false
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
additionalProperties: false
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- 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
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_count
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- sharded
- shard_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- 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
responses:
"200":
description: Returns the generated query patterns reports
headers: {}
content:
application/json:
schema:
type: object
properties:
has_next:
type: boolean
description: Whether there is a next page of results
has_prev:
type: boolean
description: Whether there is a previous page of results
cursor_start:
type: string
description: The ID of the first object in the current results
cursor_end:
type: string
description: The ID of the last object in the current results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- state
- created_at
- finished_at
- url
- download_url
- actor
additionalProperties: false
required:
- has_next
- has_prev
- cursor_start
- cursor_end
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
post:
tags:
- Query Insights reports
operationId: create_query_patterns_report
summary: Create a new query patterns report
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
"201":
description: The created query patterns download
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- state
- created_at
- finished_at
- url
- download_url
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/query-patterns/{id}:
get:
tags:
- Query Insights reports
operationId: get_query_patterns_report_status
summary: Show the status of a query patterns report
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
- name: id
in: path
required: true
description: The ID of the query patterns report
schema:
type: string
responses:
"200":
description: The retrieved query patterns download
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- state
- created_at
- finished_at
- url
- download_url
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
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
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- state
- created_at
- finished_at
- url
- download_url
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{branch}/resizes:
delete:
tags:
- Branch changes
operationId: cancel_branch_change_request
summary: Cancel a change request
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
responses:
"204":
description: Cancels a change request
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles:
get:
tags:
- Roles
operationId: list_roles
summary: List roles
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns roles
headers: {}
content:
application/json:
schema:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
expires_at:
type: string
description: When the role expires
dropped_at:
type: string
description: When the role was dropped
disabled_at:
type: string
description: When the role was disabled
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- require_where_on_delete
- require_where_on_update
additionalProperties: false
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
post:
tags:
- Roles
operationId: create_role
summary: Create role credentials
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the role
ttl:
type: integer
description: Time to live in seconds
inherited_roles:
type: array
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
description: Roles to inherit from
require_where_on_delete:
type: string
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
description: Require WHERE clause on UPDATE statements
additionalProperties: false
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
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
expires_at:
type: string
description: When the role expires
dropped_at:
type: string
description: When the role was dropped
disabled_at:
type: string
description: When the role was disabled
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- require_where_on_delete
- require_where_on_update
additionalProperties: false
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`create_production_branch_password`, `create_production_read_only_branch_password`, `create_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/default:
get:
tags:
- Roles
operationId: get_default_role
summary: Get the default postgres role
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
responses:
"200":
description: Returns the default postgres role
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
expires_at:
type: string
description: When the role expires
dropped_at:
type: string
description: When the role was dropped
disabled_at:
type: string
description: When the role was disabled
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- require_where_on_delete
- require_where_on_update
additionalProperties: false
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/reset-default:
post:
tags:
- Roles
operationId: reset_default_role
summary: Reset default credentials
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
responses:
"200":
description: Returns the new credentials
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
expires_at:
type: string
description: When the role expires
dropped_at:
type: string
description: When the role was dropped
disabled_at:
type: string
description: When the role was disabled
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- require_where_on_delete
- require_where_on_update
additionalProperties: false
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`delete_production_branch_password`, `delete_production_read_only_branch_password`, `delete_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/{id}:
get:
tags:
- Roles
operationId: get_role
summary: Get a role
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
responses:
"200":
description: Returns a role
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
expires_at:
type: string
description: When the role expires
dropped_at:
type: string
description: When the role was dropped
disabled_at:
type: string
description: When the role was disabled
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- require_where_on_delete
- require_where_on_update
additionalProperties: false
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
patch:
tags:
- Roles
operationId: update_role
summary: Update role name
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The new name of the role
require_where_on_delete:
type: string
description: Require WHERE clause on DELETE statements
require_where_on_update:
type: string
description: Require WHERE clause on UPDATE statements
additionalProperties: false
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
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
expires_at:
type: string
description: When the role expires
dropped_at:
type: string
description: When the role was dropped
disabled_at:
type: string
description: When the role was disabled
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- require_where_on_delete
- require_where_on_update
additionalProperties: false
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`create_production_branch_password`, `create_production_read_only_branch_password`, `create_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
delete:
tags:
- Roles
operationId: delete_role
summary: Delete role credentials
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
successor:
type: string
description: The optional role to reassign ownership to before dropping
additionalProperties: false
responses:
"204":
description: Deletes the role credentials
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`delete_production_branch_password`, `delete_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
additionalProperties: false
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
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
expires_at:
type: string
description: When the role expires
dropped_at:
type: string
description: When the role was dropped
disabled_at:
type: string
description: When the role was disabled
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- require_where_on_delete
- require_where_on_update
additionalProperties: false
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`create_production_branch_password`, `create_production_read_only_branch_password`, `create_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/roles/{id}/reset:
post:
tags:
- Roles
operationId: reset_role
summary: Reset a role's password
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: branch
in: path
required: true
description: "Branch name from `list_branches`. Example: `main`."
schema:
type: string
- name: id
in: path
required: true
description: The ID of the role
schema:
type: string
responses:
"200":
description: Returns the role with new password
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
expires_at:
type: string
description: When the role expires
dropped_at:
type: string
description: When the role was dropped
disabled_at:
type: string
description: When the role was disabled
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- require_where_on_delete
- require_where_on_update
additionalProperties: false
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`delete_production_branch_password`, `delete_production_read_only_branch_password`, `delete_branch_password`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Database | `manage_passwords`, `manage_production_branch_passwords`, `manage_read_only_passwords`, `manage_production_read_only_passwords` |
| Branch | `manage_passwords`, `manage_read_only_passwords` |
/organizations/{organization}/databases/{database}/branches/{branch}/safe-migrations:
post:
tags:
- Database branches
operationId: enable_safe_migrations
summary: Enable safe migrations for a branch
parameters:
- name: organization
in: path
required: true
description: The name of the organization the branch belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the branch belongs to
schema:
type: string
- name: branch
in: path
required: true
description: The name of the branch
schema:
type: string
responses:
"200":
description: Returns the branch with safe migrations enabled
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_count
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- sharded
- shard_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- 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
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_count
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- sharded
- shard_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- 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
additionalProperties: false
required:
- name
- html
- raw
additionalProperties: false
required:
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/branches/{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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
lint_error:
type: string
description: Code representing the type of error
subject_type:
type: string
enum:
- table
- vschema
- routing_rules
description: The subject for the errors
keyspace_name:
type: string
description: The keyspace of the schema with the error
table_name:
type: string
description: The table with the error
error_description:
type: string
description: A description for the error that occurred
docs_url:
type: string
description: A link to the documentation related to the error
column_name:
type: string
description: The column in a table relevant to the error
foreign_key_column_names:
items:
type: string
type: array
description: A list of invalid foreign key columns in a table
auto_increment_column_names:
items:
type: string
type: array
description: A list of invalid auto-incremented columns
charset_name:
type: string
description: The charset of the schema
engine_name:
type: string
description: The engine of the schema
vindex_name:
type: string
description: The name of the vindex for the schema
json_path:
type: string
description: The path for an invalid JSON column
check_constraint_name:
type: string
description: The name of the invalid check constraint
enum_value:
type: string
description: The name of the invalid enum value
partitioning_type:
type: string
description: The name of the invalid partitioning type
partition_name:
type: string
description: The name of the invalid partition in the schema
additionalProperties: false
required:
- lint_error
- subject_type
- keyspace_name
- table_name
- error_description
- docs_url
- column_name
- foreign_key_column_names
- auto_increment_column_names
- charset_name
- engine_name
- vindex_name
- json_path
- check_constraint_name
- enum_value
- partitioning_type
- partition_name
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
| Branch | `read_branch` |
/organizations/{organization}/databases/{database}/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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- schema
- role
- cidrs
- created_at
- updated_at
- deleted_at
- actor
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"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.
additionalProperties: false
required:
- cidrs
responses:
"201":
description: Returns the created IP restriction entry
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- schema
- role
- cidrs
- created_at
- updated_at
- deleted_at
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Invalid parameters or validation errors
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/cidrs/{id}:
get:
tags:
- Database Postgres IP restrictions
operationId: get_database_postgres_cidr
summary: Get an IP restriction entry
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the IP restriction entry
schema:
type: string
responses:
"200":
description: Returns an IP restriction entry
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- schema
- role
- cidrs
- created_at
- updated_at
- deleted_at
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Invalid parameters or validation errors
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`, `read_databases`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
put:
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.
additionalProperties: false
responses:
"200":
description: Returns the updated IP restriction entry
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- schema
- role
- cidrs
- created_at
- updated_at
- deleted_at
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Invalid parameters or validation errors
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
delete:
tags:
- Database Postgres IP restrictions
operationId: delete_database_postgres_cidr
summary: Delete an IP restriction entry
parameters:
- name: organization
in: path
required: true
description: The name of the organization the database belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the IP restriction entry
schema:
type: string
responses:
"204":
description: "IP restriction entry deleted successfully. Note: This will also remove the restriction from all database branches."
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Invalid parameters or validation errors
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/deploy-queue:
get:
tags:
- Deploy requests
operationId: get_deploy_queue
summary: Get the deploy queue
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
responses:
"200":
description: Returns the deploy queue for a database
headers: {}
content:
application/json:
schema:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |
The deploy queue returns the current list of deploy requests in the order they will be deployed.
/organizations/{organization}/databases/{database}/deploy-requests:
get:
tags:
- Deploy requests
operationId: list_deploy_requests
summary: List deploy requests
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: state
in: query
description: Filter by state of the deploy request (open, closed, deployed)
schema:
type: string
- name: branch
in: query
description: Filter by the name of the branch the deploy request is created from
schema:
type: string
- name: into_branch
in: query
description: Filter by the name of the branch the deploy request will be merged into
schema:
type: string
- name: deployed_at
in: query
description: Filter deploy requests by the date they were deployed. (e.g. 2023-01-01T00:00:00Z..2023-01-31T23:59:59Z)
schema:
type: string
- name: running_at
in: query
description: Filter deploy requests by the date they were running. (e.g. 2023-01-01T00:00:00Z..2023-01-31T23:59:59Z)
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: 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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: 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
additionalProperties: false
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: 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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
List deploy requests for a database
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
post:
tags:
- Deploy requests
operationId: create_deploy_request
summary: Create a deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
branch:
type: string
description: The name of the branch the deploy request is created from
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
notes:
type: string
description: Notes about the deploy request
auto_cutover:
type: boolean
description: Whether or not to enable auto_cutover for the deploy request. When enabled, will auto cutover to the new schema as soon as it is ready.
auto_delete_branch:
type: boolean
description: Whether or not to enable auto_delete_branch for the deploy request. When enabled, will delete the branch once the DR successfully completes.
additionalProperties: false
required:
- branch
- into_branch
responses:
"201":
description: Returns the created deploy request
headers: {}
content:
application/json:
schema:
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: 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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`, `create_deploy_requests`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_deploy_requests` |
| Database | `write_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}:
get:
tags:
- Deploy requests
operationId: get_deploy_request
summary: Get a deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: 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
additionalProperties: false
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: 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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`
**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
additionalProperties: false
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: 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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`
**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
additionalProperties: false
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: 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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`, `create_deploy_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
additionalProperties: false
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: 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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Enables or disabled the auto-apply setting for a deploy request
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/auto-delete-branch:
put:
tags:
- Deploy requests
operationId: update_auto_delete_branch
summary: Update auto-delete branch for deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
enable:
type: boolean
description: Whether or not to enable auto-delete branch for the deploy request
additionalProperties: false
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: 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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Enables or disabled the auto-delete branch setting for a deploy request
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/cancel:
post:
tags:
- Deploy requests
operationId: cancel_deploy_request
summary: Cancel a queued deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: integer
responses:
"200":
description: Returns the deploy request whose deployment was canceled
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: integer
description: The number of the deploy request
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: 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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`, `create_deploy_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
additionalProperties: false
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: 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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`, `create_deploy_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.
additionalProperties: 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
additionalProperties: false
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: 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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`, `create_deploy_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
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Get the deployment for a deploy request
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/operations:
get:
tags:
- Deploy requests
operationId: list_deploy_operations
summary: List deploy operations
parameters:
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: 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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
List deploy operations for a deploy request
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/revert:
post:
tags:
- Deploy requests
operationId: complete_revert
summary: Complete a revert
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: 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
additionalProperties: false
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: 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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`, `create_deploy_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
responses:
"200":
description: Returns an array of deploy request reviews
headers: {}
content:
application/json:
schema:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the review
body:
type: string
description: The text body of the review
html_body:
type: string
description: The HTML body of the review
state:
type: string
enum:
- commented
- approved
description: Whether the review is a comment or approval
created_at:
type: string
description: When the review was created
updated_at:
type: string
description: When the review was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- body
- html_body
- state
- created_at
- updated_at
- actor
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
post:
tags:
- Deploy requests
operationId: review_deploy_request
summary: Review a deploy request
parameters:
- name: organization
in: path
required: true
description: The name of the organization the deploy request belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the deploy request belongs to
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: 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
additionalProperties: false
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- body
- html_body
- state
- created_at
- updated_at
- actor
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Review a deploy request by either approving or commenting on the deploy request
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`approve_deploy_request`, `review_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `approve_deploy_requests` |
| Database | `approve_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/skip-revert:
post:
tags:
- Deploy requests
operationId: skip_revert_period
summary: Skip revert period
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: 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
additionalProperties: false
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: 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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Skips the revert period for a deploy request
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/deploy-requests/{number}/throttler:
get:
tags:
- Deploy requests
operationId: get_deploy_request_throttler
summary: Get deploy request throttler configurations
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: 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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: A throttler ratio between 0 and 95 that applies to migrations in this specific keyspace
additionalProperties: false
required:
- keyspace_name
- ratio
additionalProperties: false
required:
- keyspaces
- configurable
- configurations
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |
patch:
tags:
- Deploy requests
operationId: update_deploy_request_throttler
summary: Update deploy request throttler configurations
parameters:
- name: organization
in: path
required: true
description: The name of the deploy request's organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the deploy request's database
schema:
type: string
- name: number
in: path
required: true
description: The number of the deploy request
schema:
type: 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'
additionalProperties: false
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: A throttler ratio between 0 and 95 that applies to migrations in this specific keyspace
additionalProperties: false
required:
- keyspace_name
- ratio
additionalProperties: false
required:
- keyspaces
- configurable
- configurations
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the read-only region
display_name:
type: string
description: The name of the read-only region
created_at:
type: string
description: When the read-only region was created
updated_at:
type: string
description: When the read-only region was last updated
ready_at:
type: string
description: When the read-only region was ready to serve queries
ready:
type: boolean
description: Whether or not the read-only region is ready to serve queries
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
additionalProperties: false
required:
- id
- display_name
- created_at
- updated_at
- ready_at
- ready
- actor
- region
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
List read-only regions for the database's default branch
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`, `delete_database`, `write_database`, `read_branch`, `delete_branch`, `create_branch`, `delete_production_branch`, `connect_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `delete_branch_password`, `delete_production_branch_password`, `delete_production_read_only_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_comment`, `create_comment`, `restore_backup`, `restore_production_branch_backup`, `read_backups`, `write_backups`, `delete_backups`, `delete_production_branch_backups`, `write_branch_vschema`, `write_production_branch_vschema`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_branches` |
| Database | `read_branches` |
/organizations/{organization}/databases/{database}/regions:
get:
tags:
- Databases
operationId: list_database_regions
summary: List database regions
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns the available regions for a database
headers: {}
content:
application/json:
schema:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`, `delete_database`, `write_database`, `read_branch`, `delete_branch`, `create_branch`, `delete_production_branch`, `connect_branch`, `connect_production_branch`, `connect_production_read_only_branch`, `delete_branch_password`, `delete_production_branch_password`, `delete_production_read_only_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_comment`, `create_comment`, `restore_backup`, `restore_production_branch_backup`, `read_backups`, `write_backups`, `delete_backups`, `delete_production_branch_backups`, `write_branch_vschema`, `write_production_branch_vschema`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
/organizations/{organization}/databases/{database}/schema-recommendations:
get:
tags:
- Schema recommendations
operationId: list_schema_recommendations
summary: List schema recommendations
parameters:
- name: organization
in: path
required: true
description: "Organization name slug from `list_organizations`. Example: `acme`."
schema:
type: string
- name: database
in: path
required: true
description: "Database name slug from `list_databases`. Example: `app-db`."
schema:
type: string
- name: state
in: query
description: Filter by recommendation state
schema:
type: string
enum:
- open
- closed
responses:
"200":
description: Returns schema recommendations
headers: {}
content:
application/json:
schema:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the 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
dismissed_at:
type: string
description: When the recommendation was dismissed
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
additionalProperties: false
required:
- id
- branch_id
- number
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
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
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`
**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
dismissed_at:
type: string
description: When the recommendation was dismissed
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
additionalProperties: false
required:
- id
- branch_id
- number
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
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)
additionalProperties: false
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
dismissed_at:
type: string
description: When the recommendation was dismissed
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
additionalProperties: false
required:
- id
- branch_id
- number
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: A throttler ratio between 0 and 95 that applies to migrations in this specific keyspace
additionalProperties: false
required:
- keyspace_name
- ratio
additionalProperties: false
required:
- keyspaces
- configurable
- configurations
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`, `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'
additionalProperties: false
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: A throttler ratio between 0 and 95 that applies to migrations in this specific keyspace
additionalProperties: false
required:
- keyspace_name
- ratio
additionalProperties: false
required:
- keyspaces
- configurable
- configurations
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_deploy_request`, `create_deploy_request`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `deploy_deploy_requests` |
| Database | `deploy_deploy_requests` |
/organizations/{organization}/databases/{database}/webhooks:
get:
tags:
- Webhooks
operationId: list_webhooks
summary: List webhooks
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: page
in: query
description: If provided, specifies the page offset of returned results
schema:
type: integer
default: 1
- name: per_page
in: query
description: If provided, specifies the number of returned results
schema:
type: integer
default: 25
responses:
"200":
description: Returns a list of webhooks for a database
headers: {}
content:
application/json:
schema:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
additionalProperties: false
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
List webhooks for a database
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
post:
tags:
- Webhooks
operationId: create_webhook
summary: Create a webhook
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
url:
type: string
description: The URL the webhook will send events to
enabled:
type: boolean
description: Whether the webhook should be enabled
events:
type: array
items:
type: string
description: The events this webhook should subscribe to
additionalProperties: false
required:
- url
responses:
"201":
description: Returns the created webhook
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
additionalProperties: false
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
/organizations/{organization}/databases/{database}/webhooks/{id}:
get:
tags:
- Webhooks
operationId: get_webhook
summary: Get a webhook
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the webhook
schema:
type: string
responses:
"200":
description: Returns the webhook
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
additionalProperties: false
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_databases` |
| Database | `read_database` |
patch:
tags:
- Webhooks
operationId: update_webhook
summary: Update a webhook
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: database
in: path
required: true
description: The name of the database
schema:
type: string
- name: id
in: path
required: true
description: The ID of the webhook
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
url:
type: string
description: The URL the webhook will send events to
enabled:
type: boolean
description: Whether the webhook should be enabled
events:
type: array
items:
type: string
description: The events this webhook should subscribe to
additionalProperties: false
responses:
"200":
description: Returns the updated webhook
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
additionalProperties: false
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`write_database`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |
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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: 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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
post:
tags:
- Workflows
operationId: create_workflow
summary: Create a workflow
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name the workflow
source_keyspace:
type: string
description: Name of the source keyspace
target_keyspace:
type: string
description: Name of the target keyspace
global_keyspace:
type: string
description: Name of the global sequence keyspace
defer_secondary_keys:
type: boolean
description: Defer secondary keys
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
tables:
type: array
items:
type: string
description: List of tables to move
additionalProperties: false
required:
- name
- source_keyspace
- target_keyspace
- tables
responses:
"201":
description: Returns the workflow
headers: {}
content:
application/json:
schema:
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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}:
get:
tags:
- Workflows
operationId: get_workflow
summary: Get a workflow
parameters:
- name: organization
in: path
required: true
description: The name of the organization the workflow belongs to
schema:
type: string
- name: database
in: path
required: true
description: The name of the database the workflow belongs to
schema:
type: string
- name: number
in: path
required: true
description: The sequence number of the workflow
schema:
type: 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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/databases/{database}/workflows/{number}/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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
/organizations/{organization}/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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the invoice
total:
type: number
description: The total amount of the invoice
billing_period_start:
type: string
description: Start of the billing period
billing_period_end:
type: string
description: End of the billing period
paid:
type: boolean
description: Whether the invoice has been paid
overdue:
type: boolean
description: Whether the invoice is past due and unpaid
additionalProperties: false
required:
- id
- total
- billing_period_start
- billing_period_end
- paid
- overdue
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Get the invoices for an organization
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_invoices`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_invoices` |
/organizations/{organization}/invoices/{id}:
get:
tags:
- Invoices
operationId: get_invoice
summary: Get an invoice
parameters:
- name: organization
in: path
required: true
description: "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: number
description: The total amount of the invoice
billing_period_start:
type: string
description: Start of the billing period
billing_period_end:
type: string
description: End of the billing period
paid:
type: boolean
description: Whether the invoice has been paid
overdue:
type: boolean
description: Whether the invoice is past due and unpaid
additionalProperties: false
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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the line item
subtotal:
type: number
description: The total for the line item
description:
type: string
description: The description for the line item
metric_name:
type: string
description: The name of the billable item
database_id:
type: string
description: The ID for the billed database
database_name:
type: string
description: The name for the billed database
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- subtotal
- description
- metric_name
- database_id
- database_name
- resource
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Get the line items for an invoice
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_invoices`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_invoices` |
/organizations/{organization}/members:
get:
tags:
- Organization members
operationId: list_organization_members
summary: List organization members
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: 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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
additionalProperties: false
required:
- id
- user
- role
- created_at
- updated_at
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token 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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
additionalProperties: false
required:
- id
- user
- role
- created_at
- updated_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token 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."
additionalProperties: false
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
additionalProperties: false
required:
- id
- user
- role
- created_at
- updated_at
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token 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
requestBody:
content:
application/json:
schema:
type: object
properties:
delete_passwords:
type: boolean
description: Whether to delete all passwords associated with the member. Only available when removing other members (not yourself).
delete_service_tokens:
type: boolean
description: Whether to delete all service tokens associated with the member. Only available when removing other members (not yourself).
additionalProperties: false
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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the app
name:
type: string
description: The name of the app
redirect_uri:
type: string
description: The redirect URI of the OAuth application
domain:
type: string
description: The domain of the OAuth application. Used for verification of a valid redirect uri
created_at:
type: string
description: When the OAuth application was created
updated_at:
type: string
description: When the OAuth application was last updated
scopes:
items:
type: string
type: array
description: The scopes that the OAuth application requires on a user account
avatar:
type: string
description: The image source for the OAuth application's avatar
client_id:
type: string
description: The OAuth application's unique client id
tokens:
type: 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
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
additionalProperties: false
required:
- id
- name
- redirect_uri
- domain
- created_at
- updated_at
- scopes
- avatar
- client_id
- tokens
- dcr
- scopes_by_resource
- all_scopes_by_resource
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### 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:
items:
type: string
type: array
description: The scopes that the OAuth application requires on a user account
avatar:
type: string
description: The image source for the OAuth application's avatar
client_id:
type: string
description: The OAuth application's unique client id
tokens:
type: 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
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
additionalProperties: false
required:
- id
- name
- redirect_uri
- domain
- created_at
- updated_at
- scopes
- avatar
- client_id
- tokens
- dcr
- 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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
last_used_at:
type: string
description: When the service token was last used
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
additionalProperties: false
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
additionalProperties: false
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
additionalProperties: false
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
additionalProperties: false
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- users
- accesses
additionalProperties: false
required:
- database
- organization
- branch
- user
additionalProperties: false
required:
- id
- name
- display_name
- token
- plain_text_refresh_token
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
- service_token_accesses
- oauth_accesses_by_resource
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
List OAuth tokens created by an OAuth application
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_oauth_tokens`
/organizations/{organization}/oauth-applications/{application_id}/tokens/{token_id}:
get:
tags:
- OAuth applications
operationId: get_oauth_token
summary: Get an OAuth token
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth application belongs to
schema:
type: string
- name: application_id
in: path
required: true
description: The ID of the OAuth application
schema:
type: string
- name: token_id
in: path
required: true
description: The ID of the OAuth application token
schema:
type: string
responses:
"200":
description: Returns an OAuth token that was issued on behalf of the OAuth application
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
last_used_at:
type: string
description: When the service token was last used
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
additionalProperties: false
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
additionalProperties: false
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
additionalProperties: false
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
additionalProperties: false
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- users
- accesses
additionalProperties: false
required:
- database
- organization
- branch
- user
additionalProperties: false
required:
- id
- name
- display_name
- token
- plain_text_refresh_token
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
- service_token_accesses
- oauth_accesses_by_resource
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_oauth_tokens`
delete:
tags:
- OAuth applications
operationId: delete_oauth_token
summary: Delete an OAuth token
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth application belongs to
schema:
type: string
- name: application_id
in: path
required: true
description: The ID of the OAuth application
schema:
type: string
- name: token_id
in: path
required: true
description: The ID of the OAuth application token
schema:
type: string
responses:
"204":
description: Deletes an OAuth application's OAuth token
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`delete_oauth_tokens`
/organizations/{organization}/oauth-applications/{id}/token:
post:
tags:
- OAuth tokens
operationId: create_oauth_token
summary: Create or renew an OAuth token
parameters:
- name: organization
in: path
required: true
description: The name of the organization the OAuth application belongs to
schema:
type: string
- name: id
in: path
required: true
description: The ID of the OAuth application
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
client_id:
type: string
description: The OAuth application's client ID
client_secret:
type: string
description: The OAuth application's client secret
grant_type:
type: string
enum:
- authorization_code
- refresh_token
description: Whether an OAuth grant code or a refresh token is being exchanged for an OAuth token
code:
type: string
description: The OAuth grant code provided to your OAuth application's redirect URI. Required when grant_type is authorization_code
redirect_uri:
type: string
description: The OAuth application's redirect URI. Required when grant_type is authorization_code
refresh_token:
type: string
description: The refresh token from the original OAuth token grant. Required when grant_type is refresh_token
additionalProperties: false
required:
- client_id
- client_secret
- grant_type
responses:
"200":
description: Returns the created OAuth token
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
last_used_at:
type: string
description: When the service token was last used
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
additionalProperties: false
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
additionalProperties: false
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
additionalProperties: false
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
additionalProperties: false
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- users
- accesses
additionalProperties: false
required:
- database
- organization
- branch
- user
additionalProperties: false
required:
- id
- name
- display_name
- token
- plain_text_refresh_token
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
- service_token_accesses
- oauth_accesses_by_resource
"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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| User | `read_organizations` |
| Organization | `read_organization` |
/organizations/{organization}/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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
last_used_at:
type: string
description: When the service token was last used
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
additionalProperties: false
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
additionalProperties: false
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
additionalProperties: false
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
additionalProperties: false
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- users
- accesses
additionalProperties: false
required:
- database
- organization
- branch
- user
additionalProperties: false
required:
- id
- name
- display_name
- token
- plain_text_refresh_token
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
- service_token_accesses
- oauth_accesses_by_resource
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
List 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
additionalProperties: false
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
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
last_used_at:
type: string
description: When the service token was last used
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
additionalProperties: false
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
additionalProperties: false
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
additionalProperties: false
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
additionalProperties: false
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- users
- accesses
additionalProperties: false
required:
- database
- organization
- branch
- user
additionalProperties: false
required:
- id
- name
- display_name
- token
- plain_text_refresh_token
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
- service_token_accesses
- oauth_accesses_by_resource
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
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
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
last_used_at:
type: string
description: When the service token was last used
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
additionalProperties: false
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
additionalProperties: false
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
additionalProperties: false
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
additionalProperties: false
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- users
- accesses
additionalProperties: false
required:
- database
- organization
- branch
- user
additionalProperties: false
required:
- id
- name
- display_name
- token
- plain_text_refresh_token
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
- service_token_accesses
- oauth_accesses_by_resource
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
Get information about a service token.
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`read_service_tokens`
delete:
tags:
- Service tokens
operationId: delete_service_token
summary: Delete a service token
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: id
in: path
required: true
description: The ID of the service token
schema:
type: string
responses:
"204":
description: Service token deleted successfully
headers: {}
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |+
Delete a service token from the organization.
### Authorization
A service token must have at least one of the following access in order to use this API endpoint:
**Service Token Accesses**
`delete_service_tokens`
/organizations/{organization}/teams:
get:
tags:
- Organization teams
operationId: list_organization_teams
summary: List teams in an organization
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: q
in: query
description: Search term to filter teams by name
schema:
type: string
responses:
"200":
description: Returns teams in the organization
headers: {}
content:
application/json:
schema:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the 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
additionalProperties: false
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
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
additionalProperties: false
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
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
additionalProperties: false
required:
- id
- display_name
- creator
- members
- databases
- name
- slug
- created_at
- updated_at
- description
- managed
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"400":
description: Bad Request - Invalid operation or parameters
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Validation errors or SSO-managed teams
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_organization` |
post:
tags:
- Organization teams
operationId: create_organization_team
summary: Create an organization team
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the team
description:
type: string
description: A description of the team's purpose
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
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
additionalProperties: false
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
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
additionalProperties: false
required:
- id
- display_name
- creator
- members
- 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
additionalProperties: false
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
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
additionalProperties: false
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
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
additionalProperties: false
required:
- id
- display_name
- creator
- members
- 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
additionalProperties: false
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
additionalProperties: false
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
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
additionalProperties: false
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
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
additionalProperties: false
required:
- id
- display_name
- creator
- members
- 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
responses:
"200":
description: Returns the list of team members
headers: {}
content:
application/json:
schema:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the 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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
expires_at:
type: string
description: When the password will expire
last_used_at:
type: string
description: When the password was last used to execute a query
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
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
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plain text password, available only after create
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
additionalProperties: false
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
additionalProperties: false
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- 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
additionalProperties: false
required:
- id
- user
- actor
- created_at
- updated_at
- passwords
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"400":
description: Bad Request - Invalid operation or SSO-managed team
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"422":
description: Unprocessable Entity - Validation errors
"500":
description: Internal Server Error
description: |-
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:
**Service Token Accesses**
`read_organization`
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| Organization | `read_organization` |
post:
tags:
- Team members
operationId: add_organization_team_member
summary: Add a member to a team
parameters:
- name: organization
in: path
required: true
description: The name of the organization
schema:
type: string
- name: team
in: path
required: true
description: The slug of the team
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: The ID of the organization member to add to the team
additionalProperties: false
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
expires_at:
type: string
description: When the password will expire
last_used_at:
type: string
description: When the password was last used to execute a query
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
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
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plain text password, available only after create
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
additionalProperties: false
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
additionalProperties: false
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- 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
additionalProperties: false
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
expires_at:
type: string
description: When the password will expire
last_used_at:
type: string
description: When the password was last used to execute a query
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
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
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plain text password, available only after create
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
additionalProperties: false
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
additionalProperties: false
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- 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
additionalProperties: false
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
requestBody:
content:
application/json:
schema:
type: object
properties:
delete_passwords:
type: boolean
description: Whether to delete the member's passwords created through this team
additionalProperties: false
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:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: The cloud provider for the region
enabled:
type: boolean
description: Whether new clusters can be created in this region
public_ip_addresses:
items:
type: string
type: array
description: List of public IP addresses for the region
display_name:
type: string
description: The name of the region
location:
type: string
description: The location of the region
slug:
type: string
description: The slug identifier for the region
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |
Endpoint is available without authentication.
/user:
get:
tags:
- Users
operationId: get_current_user
summary: Get current user
responses:
"200":
description: Returns the user associated with this service token
headers: {}
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Internal Server Error
description: |-
Get the user associated with this service token
### Authorization
A OAuth token must have at least one of the following scopes in order to use this API endpoint:
**OAuth Scopes**
| Resource | Scopes |
| :------- | :---------- |
| User | `read_user` |
tags:
- name: Backups
description: |2
Resources for managing database branch backups.
- name: Branch changes
description: |2
Resources for managing cluster changes.
- name: Branch config changes
description: |2
Resources for managing branch-level configuration change requests.
- name: Cluster extensions
description: |2
Resources for managing cluster extension configuration.
- name: Branch log signatures
description: |2
Resources for retrieving branch log access signatures.
- name: Cluster parameters
description: |2
Resources for managing cluster configuration parameters.
- name: Database branch keyspaces
description: |2
Resources for managing keyspaces.
- name: Database branch passwords
description: |2
Resources for managing database branch passwords.
- name: Database Postgres IP restrictions
description: |2
Resources for managing Postgres IP restriction entries for databases.
Note: This endpoint is only available for PostgreSQL databases. For MySQL databases, use the Database Branch Passwords endpoint.
- name: Databases
description: |2
Resources for managing databases within an organization.
- name: Keyspace config changes
description: |2
Resources for managing keyspace-level configuration change requests.
- name: Keyspace VSchemas
description: |2
Resources for managing VSchemas within a keyspace.
- name: OAuth applications
description: |2
Resources for managing OAuth applications.
- name: OAuth tokens
description: |2
Resources for managing OAuth tokens.
- name: Organization members
description: |2
Resources for managing organization members and their roles.
- name: Organizations
description: |2
Resources for managing organizations.
- name: Bouncer resizes
description: |2
Resources for managing Postgres bouncer resize requests.
- name: Bouncers
description: |2
Resources for managing postgres bouncers.
- name: Roles
description: |2
Resources for managing role credentials.
- name: Query Insights reports
description: |2
Resources for downloading query insights data.
- name: Schema recommendations
description: |2
Resources for managing schema recommendations within a database.
- name: Service tokens
description: |2
API endpoints for managing service tokens within an organization.
- name: Shard config changes
description: |2
Resources for managing shard-level configuration change requests.
Only available for custom-sharded keyspaces.
- name: Traffic budgets
description: |2
Resources for managing traffic budgets.
- name: Users
description: |2
Resources for managing users.
- name: Workflows
description: |2
API endpoints for managing workflows.
- name: Deploy requests
description: |2
Resources for managing deploy requests.
- name: Webhooks
description: |2
Resources for managing database webhooks.
- name: Invoices
description: |2
Resources for managing invoices.
- name: Team members
description: |2
Resources for managing team memberships within an organization. Team members inherit access to databases assigned to their team.
Note: Teams managed through SSO/directory services cannot have members added or removed via API.
- name: Organization teams
description: |2
Resources for managing teams within an organization. Teams allow you to group members and grant them access to specific databases.
Note: Teams managed through SSO/directory services cannot be modified via API.
security:
- oauth2: []
x-readme:
explorer-enabled: false
servers:
- url: https://api.planetscale.com/v1
components:
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.planetscale.com/oauth/authorize
tokenUrl: https://auth.planetscale.com/oauth/token
scopes:
email: Read user email
openid: OpenID Connect scope
profile: Read user profile
read_databases: Read organization databases
read_user: Read user
read_organization: Read organization
write_databases: Write organization databases
write_user: Write user
write_organization: Write organization
branch:delete_backups: Delete backups
branch:delete_branch: Delete a database branch
branch:manage_passwords: Read, write, and delete branch passwords
branch:manage_read_only_passwords: Read, write, and delete read only branch passwords
branch:read_backups: Read backups
branch:read_branch: Read a database branch
branch:restore_backups: Restore this branch's backups to new branches
branch:write_backups: Create and update backups
branch:write_branch: Write a database branch
database:approve_deploy_requests: Approve deploy requests in a database
database:delete_backups: Delete backups
database:delete_branches: Delete database branches
database:delete_database: Delete a database
database:delete_members: Delete members
database:delete_production_branch_backups: Delete production backups
database:delete_production_branches: Delete a production database branch
database:demote_branches: Demote production database branches
database:deploy_deploy_requests: Deploy deploy requests in a database
database:manage_passwords: Read, write, and delete database branch passwords
database:manage_production_branch_passwords: Read, write, and delete production branch passwords
database:manage_production_read_only_passwords: Read, write, and delete production read only branch passwords in an organization
database:manage_read_only_passwords: Read, write, and delete read only branch passwords in an organization
database:promote_branches: Promote database branches
database:read_backups: Read backups
database:read_branches: Read database branches
database:read_comments: Read deploy request comments in a database
database:read_database: Read database information
database:read_deploy_requests: Read deploy requests in a database
database:read_members: Read members
database:restore_backups: Restore backups to new branches
database:restore_production_branch_backups: Restore production branch backups to new branches
database:write_backups: Create and update backups
database:write_branches: Write database branches
database:write_comments: Create deploy request comments in a database
database:write_database: Write database
database:write_deploy_requests: Create and update deploy requests in a database
database:write_members: Write members
organization:approve_deploy_requests: Approve deploy requests in an organization
organization:create_databases: Create organization databases
organization:delete_backups: Delete backups in an organization
organization:delete_branches: Delete branches in an organization
organization:delete_databases: Delete organization databases
organization:delete_members: Delete members in an organization
organization:delete_organization: Delete organization
organization:delete_production_branch_backups: Delete production backups in an organization
organization:delete_production_branches: Delete a production branch in an organization
organization:deploy_deploy_requests: Deploy deploy requests in an organization
organization:manage_passwords: Read, write, and delete branch passwords in an organization
organization:manage_production_branch_passwords: Read, write, and delete production branch passwords in an organization
organization:manage_production_read_only_passwords: Read, write, and delete production read only branch passwords in an organization
organization:manage_read_only_passwords: Read, write, and delete read only branch passwords in an organization
organization:promote_branches: Promote branches in an organization
organization:read_backups: Read backups in an organization
organization:read_branches: Read branches in an organization
organization:read_comments: Read deploy request comments in an organization
organization:read_databases: Read organization databases
organization:read_deploy_requests: Read deploy requests in an organization
organization:read_invoices: Read organization invoices
organization:read_members: Read members in an organization
organization:read_organization: Read organization
organization:restore_backups: Restore backups to new branches in an organization
organization:restore_production_branch_backups: Restore production branch backups to new branches in an organization
organization:write_backups: Create and update backups in an organization
organization:write_branches: Write branches in an organization
organization:write_comments: Create deploy request comments in an organization
organization:write_databases: Write organization databases
organization:write_deploy_requests: Create and update deploy requests in an organization
organization:write_members: Write members in an organization
organization:write_organization: Write organization
user:read_organizations: Read a user's organizations
user:read_user: Read user
user:write_user: Write user
schemas:
PaginatedBackup:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the backup
name:
type: string
description: The name of the backup
state:
type: string
enum:
- pending
- running
- success
- failed
- canceled
- ignored
description: The current state of the backup
size:
type: 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
expires_at:
type: string
description: When the backup expires
completed_at:
type: string
description: When the backup completed
deleted_at:
type: string
description: When the backup was deleted
pvc_size:
type: integer
description: Size of the PVC used for the backup
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: 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
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
next_run_at:
type: string
description: When the backup will next run
required:
type: boolean
description: Whether the policy is a required system backup
additionalProperties: false
required:
- id
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
database_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- protected
- required
- restored_branches
- actor
- backup_policy
- schema_snapshot
- database_branch
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
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
expires_at:
type: string
description: When the backup expires
completed_at:
type: string
description: When the backup completed
deleted_at:
type: string
description: When the backup was deleted
pvc_size:
type: integer
description: Size of the PVC used for the backup
protected:
type: boolean
description: Whether or not the backup is protected from deletion
required:
type: boolean
description: Whether or not the backup policy is required
restored_branches:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
backup_policy:
type: object
properties:
id:
type: string
description: The ID of the backup policy
name:
type: string
description: The name of the backup policy
target:
type: string
enum:
- production
- development
description: Whether the policy is for production or development branches
retention_value:
type: 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
schedule_week:
type: integer
description: Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week
created_at:
type: string
description: When the backup policy was created
updated_at:
type: string
description: When the backup policy was last updated
last_ran_at:
type: string
description: When the backup was last run
next_run_at:
type: string
description: When the backup will next run
required:
type: boolean
description: Whether the policy is a required system backup
additionalProperties: false
required:
- id
- name
- target
- retention_value
- retention_unit
- frequency_value
- frequency_unit
- schedule_time
- schedule_day
- schedule_week
- created_at
- updated_at
- last_ran_at
- next_run_at
- required
schema_snapshot:
type: object
properties:
id:
type: string
description: The ID of the schema snapshot
name:
type: string
description: The name of the schema snapshot
created_at:
type: string
description: When the schema snapshot was created
updated_at:
type: string
description: When the schema snapshot was last updated
linted_at:
type: string
description: When the schema snapshot was last linted
url:
type: string
description: The URL to the schema snapshot in the PlanetScale app
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- linted_at
- url
database_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- state
- size
- estimated_storage_cost
- created_at
- updated_at
- started_at
- expires_at
- completed_at
- deleted_at
- pvc_size
- protected
- required
- restored_branches
- actor
- backup_policy
- schema_snapshot
- database_branch
PaginatedPostgresBouncerResizeRequest:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer after the resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer before the resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
completed_at:
type: string
description: The time the bouncer resize completed
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
bouncer:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
additionalProperties: false
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
additionalProperties: false
required:
- name
- display_name
- cpu
- ram
- sort_order
additionalProperties: false
required:
- id
- state
- replicas_per_cell
- parameters
- previous_replicas_per_cell
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedPostgresClusterResizeRequest:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the branch change request
restart:
items:
type: integer
type: array
description: The ports requiring a restart when changes are applied
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
completed_at:
type: string
description: The time the branch change request completed
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: The previous SKU representing the branch cluster for display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: Whether storage shrinking is enabled when autoscaling is enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
additionalProperties: false
required:
- id
- restart
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_parameters
- minimum_storage_bytes
- maximum_storage_bytes
- storage_autoscaling
- storage_shrinking
- storage_type
- storage_iops
- storage_throughput_mibs
- previous_minimum_storage_bytes
- previous_maximum_storage_bytes
- previous_storage_autoscaling
- previous_storage_shrinking
- previous_storage_type
- previous_storage_iops
- previous_storage_throughput_mibs
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PostgresClusterResizeRequest:
type: object
properties:
id:
type: string
description: The ID of the branch change request
restart:
items:
type: integer
type: array
description: The ports requiring a restart when changes are applied
state:
type: string
enum:
- queued
- pending
- resizing
- canceled
- completed
description: The state of the branch change request
started_at:
type: string
description: The time the branch change request started
completed_at:
type: string
description: The time the branch change request completed
created_at:
type: string
description: The time the branch change request was created
updated_at:
type: string
description: The time the branch change request was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cluster_name:
type: string
description: The SKU representing the branch cluster
cluster_display_name:
type: string
description: The SKU representing the branch cluster for display
cluster_metal:
type: boolean
description: Whether or not this is a metal database
replicas:
type: integer
description: The total number of replicas
parameters:
type: object
additionalProperties: true
description: The branch parameters
previous_cluster_name:
type: string
description: The previous SKU representing the branch cluster
previous_cluster_display_name:
type: string
description: The previous SKU representing the branch cluster for display
previous_cluster_metal:
type: boolean
description: Whether or not the previous SKU was a metal database
previous_replicas:
type: integer
description: The previous total number of replicas
previous_parameters:
type: object
additionalProperties: true
description: The previous branch parameters
minimum_storage_bytes:
type: integer
description: The minimum storage size in bytes
maximum_storage_bytes:
type: integer
description: The maximum storage size in bytes
storage_autoscaling:
type: boolean
description: Whether storage autoscaling is enabled
storage_shrinking:
type: boolean
description: Whether storage shrinking is enabled when autoscaling is enabled
storage_type:
type: string
enum:
- gp3
- io2
- pd_ssd
description: The storage type (gp3 or io2)
storage_iops:
type: integer
description: The storage IOPS
storage_throughput_mibs:
type: integer
description: The storage throughput in MiB/s
previous_minimum_storage_bytes:
type: integer
description: The previous minimum storage size in bytes
previous_maximum_storage_bytes:
type: integer
description: The previous maximum storage size in bytes
previous_storage_autoscaling:
type: boolean
description: Whether storage autoscaling was previously enabled
previous_storage_shrinking:
type: boolean
description: Whether storage shrinking was previously enabled
previous_storage_type:
type: string
description: The previous storage type
previous_storage_iops:
type: integer
description: The previous storage IOPS
previous_storage_throughput_mibs:
type: integer
description: The previous storage throughput in MiB/s
additionalProperties: false
required:
- id
- restart
- state
- started_at
- completed_at
- created_at
- updated_at
- actor
- cluster_name
- cluster_display_name
- cluster_metal
- replicas
- parameters
- previous_cluster_name
- previous_cluster_display_name
- previous_cluster_metal
- previous_replicas
- previous_parameters
- minimum_storage_bytes
- maximum_storage_bytes
- storage_autoscaling
- storage_shrinking
- storage_type
- storage_iops
- storage_throughput_mibs
- previous_minimum_storage_bytes
- previous_maximum_storage_bytes
- previous_storage_autoscaling
- previous_storage_shrinking
- previous_storage_type
- previous_storage_iops
- previous_storage_throughput_mibs
PaginatedDatabaseBranch:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_count
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- sharded
- shard_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
DatabaseBranch:
type: object
properties:
id:
type: string
description: The ID of the branch
name:
type: string
description: The name of the branch
created_at:
type: string
description: When the branch was created
updated_at:
type: string
description: When the branch was last updated
deleted_at:
type: string
description: When the branch was deleted
restore_checklist_completed_at:
type: string
description: When a user last marked a backup restore checklist as completed
schema_last_updated_at:
type: string
description: When the schema for the branch was last updated
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of branch
mysql_address:
type: string
description: The MySQL address for the branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
state:
type: string
enum:
- pending
- sleep_in_progress
- sleeping
- awakening
- ready
description: The current state of the branch
direct_vtgate:
type: boolean
description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
vtgate_size:
type: string
description: The size of the vtgate cluster for the branch
vtgate_count:
type: integer
description: The number of vtgate instances in the branch
cluster_name:
type: string
description: The SKU representing the branch's cluster size
cluster_iops:
type: integer
description: IOPS for the cluster
ready:
type: boolean
description: Whether or not the branch is ready to serve queries
schema_ready:
type: boolean
description: Whether or not the schema is ready for queries
metal:
type: boolean
description: Whether or not this is a metal database
production:
type: boolean
description: Whether or not the branch is a production branch
safe_migrations:
type: boolean
description: Whether or not the branch has safe migrations enabled
sharded:
type: boolean
description: Whether or not the branch is sharded
shard_count:
type: integer
description: The number of shards in the branch
stale_schema:
type: boolean
description: Whether or not the branch has a stale schema
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
restored_from_branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
private_edge_connectivity:
type: boolean
description: True if private connections are enabled
has_replicas:
type: boolean
description: True if the branch has replica servers
has_read_only_replicas:
type: boolean
description: True if the branch has read-only replica servers
html_url:
type: string
description: Planetscale app URL for the branch
url:
type: string
description: Planetscale API URL for the branch
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
parent_branch:
type: string
description: The name of the parent branch from which the branch was created
vtgate_options:
type: object
additionalProperties: true
description: VTGate configuration options
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
- restore_checklist_completed_at
- schema_last_updated_at
- kind
- mysql_address
- mysql_edge_address
- state
- direct_vtgate
- vtgate_size
- vtgate_count
- cluster_name
- cluster_iops
- ready
- schema_ready
- metal
- production
- safe_migrations
- sharded
- shard_count
- stale_schema
- actor
- restored_from_branch
- private_edge_connectivity
- has_replicas
- has_read_only_replicas
- html_url
- url
- region
- parent_branch
- vtgate_options
PaginatedSchemaLintError:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
lint_error:
type: string
description: Code representing the type of error
subject_type:
type: string
enum:
- table
- vschema
- routing_rules
description: The subject for the errors
keyspace_name:
type: string
description: The keyspace of the schema with the error
table_name:
type: string
description: The table with the error
error_description:
type: string
description: A description for the error that occurred
docs_url:
type: string
description: A link to the documentation related to the error
column_name:
type: string
description: The column in a table relevant to the error
foreign_key_column_names:
items:
type: string
type: array
description: A list of invalid foreign key columns in a table
auto_increment_column_names:
items:
type: string
type: array
description: A list of invalid auto-incremented columns
charset_name:
type: string
description: The charset of the schema
engine_name:
type: string
description: The engine of the schema
vindex_name:
type: string
description: The name of the vindex for the schema
json_path:
type: string
description: The path for an invalid JSON column
check_constraint_name:
type: string
description: The name of the invalid check constraint
enum_value:
type: string
description: The name of the invalid enum value
partitioning_type:
type: string
description: The name of the invalid partitioning type
partition_name:
type: string
description: The name of the invalid partition in the schema
additionalProperties: false
required:
- lint_error
- subject_type
- keyspace_name
- table_name
- error_description
- docs_url
- column_name
- foreign_key_column_names
- auto_increment_column_names
- charset_name
- engine_name
- vindex_name
- json_path
- check_constraint_name
- enum_value
- partitioning_type
- partition_name
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PostgresClusterExtension:
type: object
properties:
id:
type: string
description: The ID of the extension
name:
type: string
description: The name of the extension
description:
type: string
description: The description of the extension
internal:
type: boolean
description: The internal state of the extension
shared_preload_allowed:
type: boolean
description: Whether the extension can be added to shared_preload_libraries
url:
type: string
description: The URL of the extension
available:
type: boolean
description: Whether the extension is available on the current cluster image
unavailable_reason:
type: string
description: The reason the extension is unavailable (e.g., 'container_upgrade_required')
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
namespace:
type: string
enum:
- patroni
- pgconf
- pgbouncer
description: The namespace of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
extension:
type: boolean
description: Configures an extension
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- seconds
- select
- string
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- name
- display_name
- namespace
- category
- description
- extension
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
additionalProperties: false
required:
- id
- name
- description
- internal
- shared_preload_allowed
- url
- available
- unavailable_reason
- parameters
PostgresClusterParameter:
type: object
properties:
id:
type: string
description: The ID of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
namespace:
type: string
enum:
- patroni
- pgconf
- pgbouncer
description: The namespace of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
extension:
type: boolean
description: Configures an extension
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- boolean
- bytes
- float
- integer
- seconds
- select
- string
- time
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- name
- display_name
- namespace
- category
- description
- extension
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
PaginatedDatabaseBranchKeyspace:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
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
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
additionalProperties: false
required:
- strategy
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
additionalProperties: false
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
additionalProperties: false
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_pending
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
DatabaseBranchKeyspace:
type: object
properties:
id:
type: string
description: The ID of the keyspace
name:
type: string
description: Name of the keyspace
shards:
type: integer
description: The number of keyspace shards
sharded:
type: boolean
description: If the keyspace is sharded
replicas:
type: integer
description: Total number of replicas in the keyspace
extra_replicas:
type: integer
description: Number of extra replicas in the keyspace
created_at:
type: string
description: When the keyspace was created
updated_at:
type: string
description: When the keyspace was last updated
cluster_name:
type: string
description: The SKU representing the keyspace cluster size
cluster_display_name:
type: string
description: The SKU representing the keyspace cluster size for display
resizing:
type: boolean
description: Is the keyspace currently resizing
resize_pending:
type: boolean
description: Is the keyspace awaiting a resize
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
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
additionalProperties: false
required:
- strategy
vreplication_flags:
type: object
properties:
optimize_inserts:
type: boolean
description: Enable optimized inserts
allow_no_blob_binlog_row_image:
type: boolean
description: Allow no blob binlog row image
vplayer_batching:
type: boolean
description: Enable VPlayer batching
additionalProperties: false
required:
- optimize_inserts
- allow_no_blob_binlog_row_image
- vplayer_batching
mysqld_options:
type: object
additionalProperties: true
description: MySQL daemon configuration options
vttablet_options:
type: object
additionalProperties: true
description: VTTablet configuration options
additionalProperties: false
required:
- id
- name
- shards
- sharded
- replicas
- extra_replicas
- created_at
- updated_at
- cluster_name
- cluster_display_name
- resizing
- resize_pending
- ready
- metal
- default
- imported
- vector_pool_allocation
- node_ttl_strategy
- replication_durability_constraints
- vreplication_flags
- mysqld_options
- vttablet_options
PaginatedDatabaseBranchPassword:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
expires_at:
type: string
description: When the password will expire
last_used_at:
type: string
description: When the password was last used to execute a query
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
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
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plain text password, available only after create
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
additionalProperties: false
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
additionalProperties: false
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- 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
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
DatabaseBranchPassword:
type: object
properties:
id:
type: string
description: The ID for the password
name:
type: string
description: The display name for the password
role:
type: string
enum:
- reader
- writer
- admin
- readwriter
description: The role for the password
cidrs:
items:
type: string
type: array
description: List of IP addresses or CIDR ranges that can use this password
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
expires_at:
type: string
description: When the password will expire
last_used_at:
type: string
description: When the password was last used to execute a query
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
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
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plain text password, available only after create
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
additionalProperties: false
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
additionalProperties: false
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- direct_vtgate_addresses
- ttl_seconds
- access_host_url
- access_host_regional_url
- access_host_regional_urls
- actor
- region
- username
- plain_text
- replica
- renewable
- database_branch
PaginatedPostgresClusterCidr:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- schema
- role
- cidrs
- created_at
- updated_at
- deleted_at
- actor
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PostgresClusterCidr:
type: object
properties:
id:
type: string
description: The ID of the IP allowlist entry
schema:
type: string
description: The schema name to restrict access to (optional)
role:
type: string
description: The role to restrict access to (optional)
cidrs:
items:
type: string
type: array
description: List of CIDR ranges
created_at:
type: string
description: When the entry was created
updated_at:
type: string
description: When the entry was updated
deleted_at:
type: string
description: When the entry was deleted
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- schema
- role
- cidrs
- created_at
- updated_at
- deleted_at
- actor
PaginatedDatabase:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the database
url:
type: string
description: The URL to the database API endpoint
branches_url:
type: string
description: The URL to retrieve this database's branches via the API
branches_count:
type: 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
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: If the database has reached its backup restored branch limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
finished_at:
type: string
description: When the import finished
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
additionalProperties: false
required:
- hostname
- port
- database
additionalProperties: false
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: Whether an approval is required to deploy schema changes to this database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
allow_data_branching:
type: boolean
description: Whether seeding branches with data is enabled for all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: Whether to automatically manage Rails migrations during deploy requests
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data
migration_framework:
type: string
description: Framework used for applying migrations
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
additionalProperties: false
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- issues_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- data_import
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- resizing
- resize_queued
- allow_data_branching
- foreign_keys_enabled
- automatic_migrations
- restrict_branch_region
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- migration_table_name
- migration_framework
- created_at
- updated_at
- schema_last_updated_at
- kind
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
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
multiple_admins_required_for_deletion:
type: boolean
description: If the database requires multiple admins for deletion
ready:
type: boolean
description: If the database is ready to be used
at_backup_restore_branches_limit:
type: boolean
description: If the database has reached its backup restored branch limit
at_development_branch_usage_limit:
type: boolean
description: If the database has reached its development branch limit
data_import:
type: object
properties:
state:
type: string
description: State of the data import
import_check_errors:
type: string
description: Errors encountered during the import check
started_at:
type: string
description: When the import started
finished_at:
type: string
description: When the import finished
data_source:
type: object
properties:
hostname:
type: string
description: Hostname of the data source
port:
type: integer
description: Port of the data source
database:
type: string
description: Database name of the data source
additionalProperties: false
required:
- hostname
- port
- database
additionalProperties: false
required:
- state
- import_check_errors
- started_at
- finished_at
- data_source
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
html_url:
type: string
description: The URL to see this database's branches in the web UI
name:
type: string
description: Name of the database
state:
type: string
enum:
- pending
- importing
- sleep_in_progress
- sleeping
- awakening
- import_ready
- ready
description: State of the database
sharded:
type: boolean
description: If the database is sharded
default_branch_shard_count:
type: integer
description: Number of shards in the default branch
default_branch_read_only_regions_count:
type: integer
description: Number of read only regions in the default branch
default_branch_table_count:
type: integer
description: Number of tables in the default branch schema
default_branch:
type: string
description: The default branch for the database
require_approval_for_deploy:
type: boolean
description: Whether an approval is required to deploy schema changes to this database
resizing:
type: boolean
description: True if a branch is currently resizing
resize_queued:
type: boolean
description: True if a branch has a queued resize request
allow_data_branching:
type: boolean
description: Whether seeding branches with data is enabled for all branches
foreign_keys_enabled:
type: boolean
description: Whether foreign key constraints are enabled
automatic_migrations:
type: boolean
description: Whether to automatically manage Rails migrations during deploy requests
restrict_branch_region:
type: boolean
description: Whether to restrict branch creation to one region
insights_raw_queries:
type: boolean
description: Whether raw SQL queries are collected
plan:
type: string
description: The database plan
insights_enabled:
type: boolean
description: True if query insights is enabled for the database
production_branch_web_console:
type: boolean
description: Whether web console is enabled for production branches
migration_table_name:
type: string
description: Table name to use for copying schema migration data
migration_framework:
type: string
description: Framework used for applying migrations
created_at:
type: string
description: When the database was created
updated_at:
type: string
description: When the database was last updated
schema_last_updated_at:
type: string
description: When the default branch schema was last changed.
kind:
type: string
enum:
- mysql
- postgresql
description: The kind of database
additionalProperties: false
required:
- id
- url
- branches_url
- branches_count
- open_schema_recommendations_count
- development_branches_count
- production_branches_count
- issues_count
- multiple_admins_required_for_deletion
- ready
- at_backup_restore_branches_limit
- at_development_branch_usage_limit
- data_import
- region
- html_url
- name
- state
- sharded
- default_branch_shard_count
- default_branch_read_only_regions_count
- default_branch_table_count
- default_branch
- require_approval_for_deploy
- resizing
- resize_queued
- allow_data_branching
- foreign_keys_enabled
- automatic_migrations
- restrict_branch_region
- insights_raw_queries
- plan
- insights_enabled
- production_branch_web_console
- migration_table_name
- migration_framework
- created_at
- updated_at
- schema_last_updated_at
- kind
PaginatedPlanetscaleRegion:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedDatabaseBranchReadOnlyRegion:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the read-only region
display_name:
type: string
description: The name of the read-only region
created_at:
type: string
description: When the read-only region was created
updated_at:
type: string
description: When the read-only region was last updated
ready_at:
type: string
description: When the read-only region was ready to serve queries
ready:
type: boolean
description: Whether or not the read-only region is ready to serve queries
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
additionalProperties: false
required:
- id
- display_name
- created_at
- updated_at
- ready_at
- ready
- actor
- region
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
configurations:
type: array
items:
type: object
properties:
keyspace_name:
type: string
description: Name of keyspace this throttler ratio applies to
ratio:
type: number
description: A throttler ratio between 0 and 95 that applies to migrations in this specific keyspace
additionalProperties: false
required:
- keyspace_name
- ratio
additionalProperties: false
required:
- keyspaces
- configurable
- configurations
PaginatedOauthApplication:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the app
name:
type: string
description: The name of the app
redirect_uri:
type: string
description: The redirect URI of the OAuth application
domain:
type: string
description: The domain of the OAuth application. Used for verification of a valid redirect uri
created_at:
type: string
description: When the OAuth application was created
updated_at:
type: string
description: When the OAuth application was last updated
scopes:
items:
type: string
type: array
description: The scopes that the OAuth application requires on a user account
avatar:
type: string
description: The image source for the OAuth application's avatar
client_id:
type: string
description: The OAuth application's unique client id
tokens:
type: 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
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
additionalProperties: false
required:
- id
- name
- redirect_uri
- domain
- created_at
- updated_at
- scopes
- avatar
- client_id
- tokens
- dcr
- scopes_by_resource
- all_scopes_by_resource
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
OauthApplication:
type: object
properties:
id:
type: string
description: The ID of the app
name:
type: string
description: The name of the app
redirect_uri:
type: string
description: The redirect URI of the OAuth application
domain:
type: string
description: The domain of the OAuth application. Used for verification of a valid redirect uri
created_at:
type: string
description: When the OAuth application was created
updated_at:
type: string
description: When the OAuth application was last updated
scopes:
items:
type: string
type: array
description: The scopes that the OAuth application requires on a user account
avatar:
type: string
description: The image source for the OAuth application's avatar
client_id:
type: string
description: The OAuth application's unique client id
tokens:
type: 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
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
additionalProperties: false
required:
- id
- name
- redirect_uri
- domain
- created_at
- updated_at
- scopes
- avatar
- client_id
- tokens
- dcr
- scopes_by_resource
- all_scopes_by_resource
PaginatedServiceToken:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
last_used_at:
type: string
description: When the service token was last used
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
additionalProperties: false
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
additionalProperties: false
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
additionalProperties: false
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
additionalProperties: false
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- users
- accesses
additionalProperties: false
required:
- database
- organization
- branch
- user
additionalProperties: false
required:
- id
- name
- display_name
- token
- plain_text_refresh_token
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
- service_token_accesses
- oauth_accesses_by_resource
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
ServiceToken:
type: object
properties:
id:
type: string
description: The ID of the service token
name:
type: string
description: The name of the service token
display_name:
type: string
description: The display name of the service token
token:
type: string
description: The plaintext token. Available only after create.
plain_text_refresh_token:
type: string
description: The plaintext refresh token. Available only after create.
avatar_url:
type: string
description: The image source for the avatar of the service token
created_at:
type: string
description: When the service token was created
updated_at:
type: string
description: When the service token was last updated
expires_at:
type: string
description: When the service token will expire
last_used_at:
type: string
description: When the service token was last used
actor_id:
type: string
description: The ID of the actor on whose behalf the service token was created
actor_display_name:
type: string
description: The name of the actor on whose behalf the service token was created
actor_type:
type: string
description: The type of the actor on whose behalf the service token was created
service_token_accesses:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the service token access
access:
type: string
description: The name of the service token access
description:
type: string
description: The description of the service token access
resource_name:
type: string
description: The name of the resource the service token access gives access to
resource_id:
type: string
description: The ID of the resource the service token access gives access to
resource_type:
type: string
description: The type of the resource the service token access gives access to
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- access
- description
- resource_name
- resource_id
- resource_type
- resource
oauth_accesses_by_resource:
type: object
properties:
database:
type: object
properties:
databases:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the database the token has access to
id:
type: string
description: the id of the database the token has access to
organization:
type: string
description: the name of the database's organization
url:
type: string
description: the planetscale app url for the database
additionalProperties: false
required:
- name
- id
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- databases
- accesses
organization:
type: object
properties:
organizations:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the organization
id:
type: string
description: the id of the organization
url:
type: string
description: the planetscale app url for the organization
additionalProperties: false
required:
- name
- id
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- organizations
- accesses
branch:
type: object
properties:
branches:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the branch
id:
type: string
description: the id of the branch
database:
type: string
description: the name of the database the branch belongs to
organization:
type: string
description: the name of the organization the branch belongs to
url:
type: string
description: the planetscale app url for the branch
additionalProperties: false
required:
- name
- id
- database
- organization
- url
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- branches
- accesses
user:
type: object
properties:
users:
type: array
items:
type: object
properties:
name:
type: string
description: the name of the user
id:
type: string
description: the id of the user
additionalProperties: false
required:
- name
- id
accesses:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the access scope
description:
type: string
description: The scope description
additionalProperties: false
required:
- name
- description
additionalProperties: false
required:
- users
- accesses
additionalProperties: false
required:
- database
- organization
- branch
- user
additionalProperties: false
required:
- id
- name
- display_name
- token
- plain_text_refresh_token
- avatar_url
- created_at
- updated_at
- expires_at
- last_used_at
- actor_id
- actor_display_name
- actor_type
- service_token_accesses
- oauth_accesses_by_resource
PaginatedOrganizationMembership:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
additionalProperties: false
required:
- id
- user
- role
- created_at
- updated_at
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
role:
type: string
enum:
- member
- admin
description: The role of the user in the organization
created_at:
type: string
description: When the membership was created
updated_at:
type: string
description: When the membership was last updated
additionalProperties: false
required:
- id
- user
- role
- created_at
- updated_at
PaginatedOrganization:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the organization
name:
type: string
description: The name of the organization
billing_email:
type: string
description: The billing email of the organization
created_at:
type: string
description: When the organization was created
updated_at:
type: string
description: When the organization was last updated
plan:
type: string
description: The billing plan of the organization
valid_billing_info:
type: boolean
description: Whether or not the organization's billing information is valid
sso:
type: boolean
description: Whether or not SSO is enabled on the organization
sso_directory:
type: boolean
description: Whether or not the organization uses an SSO directory
single_tenancy:
type: boolean
description: Whether or not the organization has single tenancy enabled
managed_tenancy:
type: boolean
description: Whether or not the organization has managed tenancy enabled
has_past_due_invoices:
type: boolean
description: Whether or not the organization has past due billing invoices
database_count:
type: integer
description: The number of databases in the organization
sso_portal_url:
type: string
description: The URL of the organization's SSO portal
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: Whether or not the IdP provider is be responsible for managing roles in PlanetScale
invoice_budget_amount:
type: number
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: 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
additionalProperties: false
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- has_past_due_invoices
- database_count
- sso_portal_url
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
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
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
features:
type: object
additionalProperties: true
description: Features that can be enabled on the organization
idp_managed_roles:
type: boolean
description: Whether or not the IdP provider is be responsible for managing roles in PlanetScale
invoice_budget_amount:
type: number
description: The expected monthly budget for the organization
keyspace_shard_limit:
type: 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
additionalProperties: false
required:
- id
- name
- billing_email
- created_at
- updated_at
- plan
- valid_billing_info
- sso
- sso_directory
- single_tenancy
- managed_tenancy
- has_past_due_invoices
- database_count
- sso_portal_url
- features
- idp_managed_roles
- invoice_budget_amount
- keyspace_shard_limit
- has_card
- payment_info_required
ClusterSizeSkuSerializer:
type: object
properties:
name:
type: string
description: The name of the cluster SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The number of CPUs
storage:
type: integer
description: The amount of storage in bytes
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)
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
replica_rate:
type: number
description: The replica rate for the cluster SKU
rate:
type: number
description: The rate for the cluster SKU
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)
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
additionalProperties: false
required:
- name
- display_name
- cpu
- storage
- ram
- metal
- enabled
- provider
- default_vtgate
- default_vtgate_rate
- sort_order
- architecture
- development
- production
PaginatedAuditLogEvent:
type: object
properties:
has_next:
type: boolean
description: Whether there is a next page of results
has_prev:
type: boolean
description: Whether there is a previous page of results
cursor_start:
type: string
description: The ID of the first object in the current results
cursor_end:
type: string
description: The ID of the last object in the current results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the audit log
actor_id:
type: string
description: The ID of the actor
actor_type:
type: string
description: The type of the actor. Such as 'User' or 'ServiceToken'
auditable_id:
type: string
description: The ID of the auditable object
auditable_type:
type: string
description: The type of the auditable. Such as 'Organization' or 'Database'
target_id:
type: string
description: The ID of the target
target_type:
type: string
description: The type of the target. Such as 'DatabaseBranch' or 'DatabaseBranchPassword'
location:
type: string
description: The location of the actor based on their IP address
target_display_name:
type: string
description: The name of the target
audit_action:
type: string
description: The action that was taken
action:
type: string
description: The action that was taken
actor_display_name:
type: string
description: The name of the actor
auditable_display_name:
type: string
description: The name of the auditable object
remote_ip:
type: string
description: The IP address of the actor
created_at:
type: string
description: When the audit log was created
updated_at:
type: string
description: When the audit log was last updated
metadata:
type: object
additionalProperties: true
description: Additional metadata containing details about the change
additionalProperties: false
required:
- id
- actor_id
- actor_type
- auditable_id
- auditable_type
- target_id
- target_type
- location
- target_display_name
- audit_action
- action
- actor_display_name
- auditable_display_name
- remote_ip
- created_at
- updated_at
- metadata
additionalProperties: false
required:
- has_next
- has_prev
- cursor_start
- cursor_end
- data
PostgresBouncerResizeRequest:
type: object
properties:
id:
type: string
description: The ID of the bouncer resize
state:
type: string
enum:
- pending
- resizing
- canceled
- completed
description: The state of the bouncer resize
replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer after the resize
parameters:
type: object
additionalProperties: true
description: The bouncer parameters
previous_replicas_per_cell:
type: integer
description: The number of replicas per cell for the bouncer before the resize
previous_parameters:
type: object
additionalProperties: true
description: The previous bouncer parameters
started_at:
type: string
description: The time the bouncer resize started
completed_at:
type: string
description: The time the bouncer resize completed
created_at:
type: string
description: The time the bouncer resize was created
updated_at:
type: string
description: The time the bouncer resize was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
bouncer:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
additionalProperties: false
required:
- name
- display_name
- cpu
- ram
- sort_order
previous_sku:
type: object
properties:
name:
type: string
description: The name of the Postgres bouncer SKU
display_name:
type: string
description: The display name
cpu:
type: string
description: The CPU allocation
ram:
type: integer
description: The amount of memory in bytes
sort_order:
type: integer
description: The sort order of the Postgres bouncer SKU
additionalProperties: false
required:
- name
- display_name
- cpu
- ram
- sort_order
additionalProperties: false
required:
- id
- state
- replicas_per_cell
- parameters
- previous_replicas_per_cell
- previous_parameters
- started_at
- completed_at
- created_at
- updated_at
- actor
- bouncer
- sku
- previous_sku
PaginatedPostgresBouncer:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the bouncer
name:
type: string
description: The name of the bouncer
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
additionalProperties: false
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
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
description: The namespace of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- namespace
- name
- display_name
- category
- description
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
additionalProperties: false
required:
- id
- name
- sku
- target
- replicas_per_cell
- created_at
- updated_at
- deleted_at
- actor
- branch
- parameters
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
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
additionalProperties: false
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
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
parameters:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the parameter
namespace:
type: string
enum:
- pgbouncer
description: The namespace of the parameter
name:
type: string
description: The name of the parameter
display_name:
type: string
description: The display name of the parameter
category:
type: string
description: The category of the parameter
description:
type: string
description: The description of the parameter
immutable:
type: boolean
description: Whether the parameter can be changed
parameter_type:
type: string
enum:
- array
- integer
- seconds
- select
- string
description: The type of the parameter
default_value:
type: string
description: The default value of the parameter
value:
type: string
description: The configured value of the parameter
required:
type: boolean
description: Whether the parameter is required
created_at:
type: string
description: When the parameter was created
updated_at:
type: string
description: When the parameter was last updated
restart:
type: boolean
description: True if processes require a server restart on change
max:
type: number
description: The maximum value of the parameter
min:
type: number
description: The minimum value of the parameter
step:
type: number
description: The step change of the parameter
url:
type: string
description: The URL of the parameter
options:
items:
type: string
type: array
description: Valid options for the parameter value
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- namespace
- name
- display_name
- category
- description
- immutable
- parameter_type
- default_value
- value
- required
- created_at
- updated_at
- restart
- max
- min
- step
- url
- options
- actor
additionalProperties: false
required:
- id
- name
- sku
- target
- replicas_per_cell
- created_at
- updated_at
- deleted_at
- actor
- branch
- parameters
PaginatedPostgresRole:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
expires_at:
type: string
description: When the role expires
dropped_at:
type: string
description: When the role was dropped
disabled_at:
type: string
description: When the role was disabled
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- require_where_on_delete
- require_where_on_update
additionalProperties: false
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PostgresRole:
type: object
properties:
id:
type: string
description: The ID of the role
name:
type: string
description: The name of the role
access_host_url:
type: string
description: The database connection string
private_access_host_url:
type: string
description: The database connection string for private connections
private_connection_service_name:
type: string
description: The service name to set up private connectivity
username:
type: string
description: The database user name
password:
type: string
description: The plain text password, available only after create
database_name:
type: string
description: The database name
created_at:
type: string
description: When the role was created
updated_at:
type: string
description: When the role was updated
deleted_at:
type: string
description: When the role was deleted
expires_at:
type: string
description: When the role expires
dropped_at:
type: string
description: When the role was dropped
disabled_at:
type: string
description: When the role was disabled
drop_failed:
type: string
description: Error message available when dropping the role fails
expired:
type: boolean
description: True if the credentials are expired
default:
type: boolean
description: Whether the role is the default postgres user
ttl:
type: integer
description: Number of seconds before the credentials expire
inherited_roles:
items:
type: string
enum:
- pscale_managed
- pg_checkpoint
- pg_create_subscription
- pg_maintain
- pg_monitor
- pg_read_all_data
- pg_read_all_settings
- pg_read_all_stats
- pg_signal_backend
- pg_stat_scan_tables
- pg_use_reserved_connections
- pg_write_all_data
- postgres
type: array
description: Database roles these credentials inherit
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
additionalProperties: false
required:
- require_where_on_delete
- require_where_on_update
additionalProperties: false
required:
- id
- name
- access_host_url
- private_access_host_url
- private_connection_service_name
- username
- password
- database_name
- created_at
- updated_at
- deleted_at
- expires_at
- dropped_at
- disabled_at
- drop_failed
- expired
- default
- ttl
- inherited_roles
- branch
- actor
- query_safety_settings
PaginatedQueryPatternsDownload:
type: object
properties:
has_next:
type: boolean
description: Whether there is a next page of results
has_prev:
type: boolean
description: Whether there is a previous page of results
cursor_start:
type: string
description: The ID of the first object in the current results
cursor_end:
type: string
description: The ID of the last object in the current results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the query patterns download
state:
type: string
enum:
- pending
- completed
- failed
description: The state of the download
created_at:
type: string
description: When the download was created
finished_at:
type: string
description: When the download was finished
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- state
- created_at
- finished_at
- url
- download_url
- actor
additionalProperties: false
required:
- has_next
- has_prev
- cursor_start
- cursor_end
- data
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
url:
type: string
description: The URL to access the query patterns download
download_url:
type: string
description: The URL to download the query patterns file
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- state
- created_at
- finished_at
- url
- download_url
- actor
PaginatedPublicPlanetscaleRegionSerializer:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: The cloud provider for the region
enabled:
type: boolean
description: Whether new clusters can be created in this region
public_ip_addresses:
items:
type: string
type: array
description: List of public IP addresses for the region
display_name:
type: string
description: The name of the region
location:
type: string
description: The location of the region
slug:
type: string
description: The slug identifier for the region
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedSchemaRecommendation:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the 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
dismissed_at:
type: string
description: When the recommendation was dismissed
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
additionalProperties: false
required:
- id
- branch_id
- number
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
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
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
SchemaRecommendation:
type: object
properties:
id:
type: string
description: The ID of the schema recommendation
html_url:
type: string
description: The URL to the schema recommendation in the app
title:
type: string
description: The title of the schema recommendation
table_name:
type: string
description: The name of the table the recommendation applies to
keyspace:
type: string
description: The keyspace the recommendation applies to
ddl_statement:
type: string
description: The DDL statement to apply the recommendation
number:
type: integer
description: The number of the schema recommendation
state:
type: string
enum:
- open
- applied
- dismissed
- stale
description: The state of the recommendation
recommendation_type:
type: string
enum:
- unused_table
- unused_index
- duplicate_index
- sequence_overflow
- sequence_overflow_foreign_key
- new_index
- encoding_upgrade
- bloated_table
- bloated_index
description: The type of recommendation
created_at:
type: string
description: When the recommendation was created
updated_at:
type: string
description: When the recommendation was last updated
applied_at:
type: string
description: When the recommendation was applied
dismissed_at:
type: string
description: When the recommendation was dismissed
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
additionalProperties: false
required:
- id
- branch_id
- number
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
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
User:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
PaginatedWorkflow:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the workflow
name:
type: string
description: The name of the workflow
number:
type: 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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
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
completed_at:
type: string
description: When the workflow was completed
cancelled_at:
type: string
description: When the workflow was cancelled
reversed_at:
type: string
description: When the workflow was reversed
retried_at:
type: string
description: When the workflow was retried
data_copy_completed_at:
type: string
description: When the data copy was completed
cutover_at:
type: string
description: When the cutover was completed
replicas_switched:
type: boolean
description: Whether or not the replicas have been switched
primaries_switched:
type: boolean
description: Whether or not the primaries have been switched
switch_replicas_at:
type: string
description: When the replicas were switched
switch_primaries_at:
type: string
description: When the primaries were switched
verify_data_at:
type: string
description: When the data was verified
workflow_type:
type: string
enum:
- move_tables
description: The type of the workflow
workflow_subtype:
type: string
description: The subtype of the workflow
defer_secondary_keys:
type: boolean
description: Whether or not secondary keys are deferred
on_ddl:
type: string
enum:
- IGNORE
- STOP
- EXEC
- EXEC_IGNORE
description: The behavior when DDL changes during the workflow
workflow_errors:
type: string
description: The errors that occurred during the workflow
may_retry:
type: boolean
description: Whether or not the workflow may be retried
may_restart:
type: boolean
description: Whether or not the workflow may be restarted
verified_data_stale:
type: boolean
description: Whether or not the verified data is stale
sequence_tables_applied:
type: boolean
description: Whether or not sequence tables have been created
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
verify_data_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_replicas_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
switch_primaries_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
completed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
retried_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
reversed_cutover_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
source_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
target_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
global_keyspace:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- name
- number
- state
- created_at
- updated_at
- started_at
- completed_at
- cancelled_at
- reversed_at
- retried_at
- data_copy_completed_at
- cutover_at
- replicas_switched
- primaries_switched
- switch_replicas_at
- switch_primaries_at
- verify_data_at
- workflow_type
- workflow_subtype
- defer_secondary_keys
- on_ddl
- workflow_errors
- may_retry
- may_restart
- verified_data_stale
- sequence_tables_applied
- actor
- verify_data_by
- reversed_by
- switch_replicas_by
- switch_primaries_by
- cancelled_by
- completed_by
- retried_by
- cutover_by
- reversed_cutover_by
- branch
- source_keyspace
- target_keyspace
- global_keyspace
PaginatedDeployRequestReview:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the review
body:
type: string
description: The text body of the review
html_body:
type: string
description: The HTML body of the review
state:
type: string
enum:
- commented
- approved
description: Whether the review is a comment or approval
created_at:
type: string
description: When the review was created
updated_at:
type: string
description: When the review was last updated
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- body
- html_body
- state
- created_at
- updated_at
- actor
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
additionalProperties: false
required:
- id
- body
- html_body
- state
- created_at
- updated_at
- actor
PaginatedDatabaseDeployRequest:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the deploy request
number:
type: 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
additionalProperties: false
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: 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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
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
additionalProperties: false
required:
- id
- display_name
- avatar_url
closed_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch:
type: string
description: The name of the branch the deploy request was created from
branch_id:
type: string
description: The ID of the branch the deploy request was created from
branch_deleted:
type: boolean
description: Whether or not the deploy request branch was deleted
branch_deleted_by:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
branch_deleted_at:
type: string
description: When the deploy request branch was deleted
into_branch:
type: string
description: The name of the branch the deploy request will be merged into
into_branch_sharded:
type: boolean
description: Whether or not the branch the deploy request will be merged into is sharded
into_branch_shard_count:
type: integer
description: The number of shards the branch the deploy request will be merged into has
approved:
type: boolean
description: Whether or not the deploy request is approved
state:
type: string
enum:
- open
- closed
description: Whether the deploy request is open or closed
deployment_state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The deployment state of the deploy request
deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
num_comments:
type: 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
deployed_at:
type: string
description: When the deploy request was deployed
additionalProperties: false
required:
- id
- number
- actor
- closed_by
- branch
- branch_id
- branch_deleted
- branch_deleted_by
- branch_deleted_at
- into_branch
- into_branch_sharded
- into_branch_shard_count
- approved
- state
- deployment_state
- deployment
- num_comments
- html_url
- notes
- html_body
- created_at
- updated_at
- closed_at
- deployed_at
Deployment:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
PaginatedDeployOperation:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation
state:
type: string
enum:
- pending
- queued
- in_progress
- complete
- cancelled
- error
description: The state of the deploy operation
keyspace_name:
type: string
description: The keyspace modified by the deploy operation
table_name:
type: string
description: The name of the table modifed by the deploy operation
operation_name:
type: string
description: The operation name of the deploy operation
eta_seconds:
type: number
description: The estimated seconds until completion for the deploy operation
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedDeployment:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the deployment
auto_cutover:
type: boolean
description: Whether or not to automatically cutover once deployment is finished
auto_delete_branch:
type: boolean
description: Whether or not to automatically delete the head branch once deployment is finished
created_at:
type: string
description: When the deployment was created
cutover_at:
type: string
description: When the cutover for the deployment was initiated
cutover_expiring:
type: boolean
description: Whether or not the deployment cutover will expire soon
deploy_check_errors:
type: string
description: Deploy check errors for the deployment
finished_at:
type: string
description: When the deployment was finished
queued_at:
type: string
description: When the deployment was queued
ready_to_cutover_at:
type: string
description: When the deployment was ready for cutover
started_at:
type: string
description: When the deployment was started
state:
type: string
enum:
- pending
- ready
- no_changes
- queued
- submitting
- in_progress
- pending_cutover
- in_progress_vschema
- in_progress_cancel
- in_progress_cutover
- complete
- complete_cancel
- complete_error
- complete_pending_revert
- in_progress_revert
- in_progress_revert_vschema
- complete_revert
- complete_revert_error
- cancelled
- error
description: The state the deployment is in
submitted_at:
type: string
description: When the deployment was submitted
updated_at:
type: string
description: When the deployment was last updated
into_branch:
type: string
description: The name of the base branch the deployment will be merged into
deploy_request_number:
type: 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
progress_percentage:
type: number
description: The percent completion for the deploy operation
deploy_error_docs_url:
type: string
description: A link to documentation explaining the deploy error, if present
ddl_statement:
type: string
description: The DDL statement for the deploy operation
syntax_highlighted_ddl:
type: string
description: A syntax-highlighted DDL statement for the deploy operation
created_at:
type: string
description: When the deploy operation was created
updated_at:
type: string
description: When the deploy operation was last updated
throttled_at:
type: string
description: When the deploy operation was last throttled
can_drop_data:
type: boolean
description: Whether or not the deploy operation is capable of dropping data
table_locked:
type: boolean
description: Whether or not the table modified by the deploy operation is currently locked
table_recently_used:
type: boolean
description: Whether or not the table modified by the deploy operation was recently used
table_recently_used_at:
type: string
description: When the table modified by the deploy operation was last used
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation
deploy_errors:
type: string
description: Deploy errors for the deploy operation
additionalProperties: false
required:
- id
- state
- keyspace_name
- table_name
- operation_name
- eta_seconds
- progress_percentage
- deploy_error_docs_url
- ddl_statement
- syntax_highlighted_ddl
- created_at
- updated_at
- throttled_at
- can_drop_data
- table_locked
- table_recently_used
- table_recently_used_at
- removed_foreign_key_names
- deploy_errors
deploy_operation_summaries:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the deploy operation summary
created_at:
type: string
description: When the deploy operation summary was created
deploy_errors:
type: string
description: Deploy errors for the deploy operation summary
ddl_statement:
type: string
description: The DDL statement for the deploy operation summary
eta_seconds:
type: 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
throttled_at:
type: string
description: When the deploy operation summary was last throttled
removed_foreign_key_names:
items:
type: string
type: array
description: Names of foreign keys removed by this operation summary
shard_count:
type: 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
additionalProperties: false
required:
- id
- shard
- state
- progress_percentage
- eta_seconds
additionalProperties: false
required:
- id
- created_at
- deploy_errors
- ddl_statement
- eta_seconds
- keyspace_name
- operation_name
- progress_percentage
- state
- syntax_highlighted_ddl
- table_name
- table_recently_used_at
- throttled_at
- removed_foreign_key_names
- shard_count
- shard_names
- can_drop_data
- table_recently_used
- sharded
- operations
lint_errors:
items:
type: object
additionalProperties: true
type: array
description: Schema lint errors preventing the deployment from completing
sequential_diff_dependencies:
items:
type: object
additionalProperties: true
type: array
description: The schema dependencies that must be satisfied
lookup_vindex_operations:
items:
type: object
additionalProperties: true
type: array
description: Lookup Vitess index operations
throttler_configurations:
items:
type: object
additionalProperties: true
type: array
description: Deployment throttling configurations
deployment_revert_request:
type: object
additionalProperties: true
description: The request to revert the schema operations in this deployment
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cutover_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
cancelled_actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
schema_last_updated_at:
type: string
description: When the schema was last updated for the deployment
table_locked:
type: boolean
description: Whether or not the deployment has a table locked
locked_table_name:
type: string
description: The name of he table that is locked by the deployment
instant_ddl:
type: boolean
description: Whether or not the deployment is an instant DDL deployment
instant_ddl_eligible:
type: boolean
description: Whether or not the deployment is eligible for instant DDL
additionalProperties: false
required:
- id
- auto_cutover
- auto_delete_branch
- created_at
- cutover_at
- cutover_expiring
- deploy_check_errors
- finished_at
- queued_at
- ready_to_cutover_at
- started_at
- state
- submitted_at
- updated_at
- into_branch
- deploy_request_number
- deployable
- preceding_deployments
- deploy_operations
- deploy_operation_summaries
- lint_errors
- sequential_diff_dependencies
- lookup_vindex_operations
- throttler_configurations
- deployment_revert_request
- actor
- cutover_actor
- cancelled_actor
- schema_last_updated_at
- table_locked
- locked_table_name
- instant_ddl
- instant_ddl_eligible
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedDatabaseWebhook:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the webhook
url:
type: string
description: The URL the webhook will send events to
secret:
type: string
description: The secret used to sign the webhook payloads
enabled:
type: boolean
description: Whether the webhook is enabled
last_sent_result:
type: string
description: The last result sent by the webhook
last_sent_success:
type: boolean
description: Whether the last sent was successful
last_sent_at:
type: string
description: When the last event was sent
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
additionalProperties: false
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
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
created_at:
type: string
description: When the webhook was created
updated_at:
type: string
description: When the webhook was updated
events:
items:
type: string
enum:
- branch.ready
- branch.anomaly
- branch.out_of_memory
- branch.primary_promoted
- branch.schema_recommendation
- branch.sleeping
- branch.start_maintenance
- cluster.storage
- database.access_request
- deploy_request.closed
- deploy_request.errored
- deploy_request.in_progress
- deploy_request.opened
- deploy_request.pending_cutover
- deploy_request.queued
- deploy_request.reverted
- deploy_request.schema_applied
- keyspace.storage
- webhook.test
type: array
description: The events this webhook subscribes to
additionalProperties: false
required:
- id
- url
- secret
- enabled
- last_sent_result
- last_sent_success
- last_sent_at
- created_at
- updated_at
- events
PaginatedLineItem:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID for the line item
subtotal:
type: number
description: The total for the line item
description:
type: string
description: The description for the line item
metric_name:
type: string
description: The name of the billable item
database_id:
type: string
description: The ID for the billed database
database_name:
type: string
description: The name for the billed database
resource:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
additionalProperties: false
required:
- id
- subtotal
- description
- metric_name
- database_id
- database_name
- resource
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
PaginatedInvoice:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the invoice
total:
type: number
description: The total amount of the invoice
billing_period_start:
type: string
description: Start of the billing period
billing_period_end:
type: string
description: End of the billing period
paid:
type: boolean
description: Whether the invoice has been paid
overdue:
type: boolean
description: Whether the invoice is past due and unpaid
additionalProperties: false
required:
- id
- total
- billing_period_start
- billing_period_end
- paid
- overdue
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
Invoice:
type: object
properties:
id:
type: string
description: The ID of the invoice
total:
type: number
description: The total amount of the invoice
billing_period_start:
type: string
description: Start of the billing period
billing_period_end:
type: string
description: End of the billing period
paid:
type: boolean
description: Whether the invoice has been paid
overdue:
type: boolean
description: Whether the invoice is past due and unpaid
additionalProperties: false
required:
- id
- total
- billing_period_start
- billing_period_end
- paid
- overdue
PaginatedOrganizationTeamMembership:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the 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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
expires_at:
type: string
description: When the password will expire
last_used_at:
type: string
description: When the password was last used to execute a query
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
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
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plain text password, available only after create
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
additionalProperties: false
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
additionalProperties: false
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- 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
additionalProperties: false
required:
- id
- user
- actor
- created_at
- updated_at
- passwords
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
OrganizationTeamMembership:
type: object
properties:
id:
type: string
description: The ID of the team membership
user:
type: object
properties:
id:
type: string
description: The ID of the user
display_name:
type: string
description: The display name of the user
name:
type: string
description: The name of the user
email:
type: string
description: The email of the user
avatar_url:
type: string
description: The URL source of the user's avatar
created_at:
type: string
description: When the user was created
updated_at:
type: string
description: When the user was last updated
two_factor_auth_configured:
type: boolean
description: Whether or not the user has configured two factor authentication
default_organization:
type: object
properties:
id:
type: string
description: The ID for the resource
name:
type: string
description: The name for the resource
created_at:
type: string
description: When the resource was created
updated_at:
type: string
description: When the resource was last updated
deleted_at:
type: string
description: When the resource was deleted, if deleted
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
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
created_at:
type: string
description: When the password was created
deleted_at:
type: string
description: When the password was deleted
expires_at:
type: string
description: When the password will expire
last_used_at:
type: string
description: When the password was last used to execute a query
expired:
type: boolean
description: True if the credentials are expired
direct_vtgate:
type: boolean
description: True if the credentials connect directly to a vtgate, bypassing load balancers
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
access_host_url:
type: string
description: The host URL for the password
access_host_regional_url:
type: string
description: The regional host URL
access_host_regional_urls:
items:
type: string
type: array
description: The read-only replica host URLs
actor:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
required:
- id
- display_name
- avatar_url
region:
type: object
properties:
id:
type: string
description: The ID of the region
provider:
type: string
description: Provider for the region (ex. AWS)
enabled:
type: boolean
description: Whether or not the region is currently active
public_ip_addresses:
items:
type: string
type: array
description: Public IP addresses for the region
display_name:
type: string
description: Name of the region
location:
type: string
description: Location of the region
slug:
type: string
description: The slug of the region
current_default:
type: boolean
description: True if the region is the default for new branch creation
additionalProperties: false
required:
- id
- provider
- enabled
- public_ip_addresses
- display_name
- location
- slug
- current_default
username:
type: string
description: The username for the password
plain_text:
type: string
description: The plain text password, available only after create
replica:
type: boolean
description: Whether or not the password is for a read replica
renewable:
type: boolean
description: Whether or not the password can be renewed
database_branch:
type: object
properties:
name:
type: string
description: The name for the branch
id:
type: string
description: The ID for the branch
production:
type: boolean
description: Whether or not the branch is a production branch
mysql_edge_address:
type: string
description: The address of the MySQL provider for the branch
private_edge_connectivity:
type: boolean
description: True if private connectivity is enabled
additionalProperties: false
required:
- name
- id
- production
- mysql_edge_address
- private_edge_connectivity
additionalProperties: false
required:
- id
- name
- role
- cidrs
- created_at
- deleted_at
- expires_at
- last_used_at
- expired
- direct_vtgate
- 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
additionalProperties: false
required:
- id
- user
- actor
- created_at
- updated_at
- passwords
PaginatedOrganizationTeam:
type: object
properties:
current_page:
type: integer
description: The current page number
next_page:
type: integer
description: The next page number
next_page_url:
type: string
description: The next page of results
prev_page:
type: integer
description: The previous page number
prev_page_url:
type: string
description: The previous page of results
data:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the 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
additionalProperties: false
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
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
additionalProperties: false
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
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
additionalProperties: false
required:
- id
- display_name
- creator
- members
- databases
- name
- slug
- created_at
- updated_at
- description
- managed
additionalProperties: false
required:
- current_page
- next_page
- next_page_url
- prev_page
- prev_page_url
- data
OrganizationTeam:
type: object
properties:
id:
type: string
description: The ID of the team
display_name:
type: string
description: The display name of the team
creator:
type: object
properties:
id:
type: string
description: The ID of the actor
display_name:
type: string
description: The name of the actor
avatar_url:
type: string
description: The URL of the actor's avatar
additionalProperties: false
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
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
- deleted_at
sso:
type: boolean
description: Whether or not the user is managed by SSO
managed:
type: boolean
description: Whether or not the user is managed by an authentication provider
directory_managed:
type: boolean
description: Whether or not the user is managed by a SSO directory
email_verified:
type: boolean
description: Whether or not the user is verified by email
additionalProperties: false
required:
- id
- display_name
- name
- email
- avatar_url
- created_at
- updated_at
- two_factor_auth_configured
- default_organization
- sso
- managed
- directory_managed
- email_verified
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
additionalProperties: false
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
managed:
type: boolean
description: Whether the team is managed through SSO/directory services
additionalProperties: false
required:
- id
- display_name
- creator
- members
- databases
- name
- slug
- created_at
- updated_at
- description
- managed