PlanetScale API
© 2025 PlanetScale, Inc. version: v1 x-copyright: "© 2025 PlanetScale, Inc." paths: /organizations: get: tags: - Organizations operationId: list_organizations summary: List organizations parameters: - name: page in: query description: If provided, specifies the page offset of returned results schema: type: number default: 1 - name: per_page in: query description: If provided, specifies the number of returned results schema: type: number default: 25 responses: "200": description: Gets the organizations for the current user headers: {} content: application/json: schema: &a36 type: object properties: current_page: type: number description: The current page number next_page: type: number description: The next page number next_page_url: type: string description: The next page of results prev_page: type: number description: The previous page number prev_page_url: type: string description: The previous page of results data: type: array items: type: object properties: id: type: string description: The ID for the organization name: type: string description: The name of the organization billing_email: type: string description: The billing email of the organization created_at: type: string description: When the organization was created updated_at: type: string description: When the organization was last updated plan: type: string description: The billing plan of the organization valid_billing_info: type: boolean description: Whether or not the organization's billing information is valid sso: type: boolean description: Whether or not SSO is enabled on the organization sso_directory: type: boolean description: Whether or not the organization uses an SSO directory single_tenancy: type: boolean description: Whether or not the organization has single tenancy enabled managed_tenancy: type: boolean description: Whether or not the organization has managed tenancy enabled has_past_due_invoices: type: boolean description: Whether or not the organization has past due billing invoices database_count: type: number description: The number of databases in the organization sso_portal_url: type: string description: The URL of the organization's SSO portal features: type: object additionalProperties: true description: Features that can be enabled on the organization idp_managed_roles: type: boolean description: Whether or not the IdP provider is be responsible for managing roles in PlanetScale invoice_budget_amount: type: number description: The expected monthly budget for the organization keyspace_shard_limit: type: number description: The keyspace shard limit for the organization has_card: type: boolean description: Whether or not the organization has a payment method on file payment_info_required: type: boolean description: Whether or not the organization requires payment information additionalProperties: false required: - id - name - billing_email - created_at - updated_at - plan - valid_billing_info - sso - sso_directory - single_tenancy - managed_tenancy - has_past_due_invoices - database_count - sso_portal_url - features - idp_managed_roles - invoice_budget_amount - keyspace_shard_limit - has_card - payment_info_required additionalProperties: false required: - current_page - next_page - next_page_url - prev_page - prev_page_url - data "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- When using a service token, returns the list of organizations the service token has access to. When using an OAuth token, returns the list of organizations the user has access to. ### Authorization A OAuth token must have at least one of the following scopes in order to use this API endpoint: **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | User | `read_organizations` | /organizations/{name}: get: tags: - Organizations operationId: get_organization summary: Get an organization parameters: - name: name in: path required: true description: The name of the organization schema: type: string responses: "200": description: Returns an organization headers: {} content: application/json: schema: &a1 type: object properties: id: type: string description: The ID for the organization name: type: string description: The name of the organization billing_email: type: string description: The billing email of the organization created_at: type: string description: When the organization was created updated_at: type: string description: When the organization was last updated plan: type: string description: The billing plan of the organization valid_billing_info: type: boolean description: Whether or not the organization's billing information is valid sso: type: boolean description: Whether or not SSO is enabled on the organization sso_directory: type: boolean description: Whether or not the organization uses an SSO directory single_tenancy: type: boolean description: Whether or not the organization has single tenancy enabled managed_tenancy: type: boolean description: Whether or not the organization has managed tenancy enabled has_past_due_invoices: type: boolean description: Whether or not the organization has past due billing invoices database_count: type: number description: The number of databases in the organization sso_portal_url: type: string description: The URL of the organization's SSO portal features: type: object additionalProperties: true description: Features that can be enabled on the organization idp_managed_roles: type: boolean description: Whether or not the IdP provider is be responsible for managing roles in PlanetScale invoice_budget_amount: type: number description: The expected monthly budget for the organization keyspace_shard_limit: type: number description: The keyspace shard limit for the organization has_card: type: boolean description: Whether or not the organization has a payment method on file payment_info_required: type: boolean description: Whether or not the organization requires payment information additionalProperties: false required: - id - name - billing_email - created_at - updated_at - plan - valid_billing_info - sso - sso_directory - single_tenancy - managed_tenancy - has_past_due_invoices - database_count - sso_portal_url - features - idp_managed_roles - invoice_budget_amount - keyspace_shard_limit - has_card - payment_info_required "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_organization` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | User | `read_organizations` | | Organization | `read_organization` | patch: tags: - Organizations operationId: update_organization summary: Update an organization parameters: - name: name in: path required: true description: The name of the organization schema: type: string requestBody: content: application/json: schema: type: object properties: billing_email: type: string description: The billing email for the organization idp_managed_roles: type: boolean description: Whether or not the IdP provider is be responsible for managing roles in PlanetScale invoice_budget_amount: type: number description: The expected monthly budget for the organization additionalProperties: false responses: "200": description: Returns the updated organization headers: {} content: application/json: schema: *a1 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A OAuth token must have at least one of the following scopes in order to use this API endpoint: **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_organization` | /organizations/{name}/audit-log: get: tags: - Organizations operationId: list_audit_logs summary: List audit logs parameters: - name: name in: path required: true description: The name of the organization schema: type: string responses: "200": description: Returns the audit log events headers: {} content: application/json: schema: &a38 type: object properties: has_next: type: boolean description: Whether there is a next page of results has_prev: type: boolean description: Whether there is a previous page of results cursor_start: type: string description: The ID of the first object in the current results cursor_end: type: string description: The ID of the last object in the current results data: type: array items: type: object properties: id: type: string description: The ID for the audit log actor_id: type: string description: The ID of the actor actor_type: type: string description: The type of the actor. Such as 'User' or 'ServiceToken' auditable_id: type: string description: The ID of the auditable object auditable_type: type: string description: The type of the auditable. Such as 'Organization' or 'Database' target_id: type: string description: The ID of the target target_type: type: string description: The type of the target. Such as 'DatabaseBranch' or 'DatabaseBranchPassword' location: type: string description: The location of the actor based on their IP address target_display_name: type: string description: The name of the target audit_action: type: string description: The action that was taken action: type: string description: The action that was taken actor_display_name: type: string description: The name of the actor auditable_display_name: type: string description: The name of the auditable object remote_ip: type: string description: The IP address of the actor created_at: type: string description: When the audit log was created updated_at: type: string description: When the audit log was last updated metadata: type: object additionalProperties: true description: Additional metadata containing details about the change additionalProperties: false required: - id - actor_id - actor_type - auditable_id - auditable_type - target_id - target_type - location - target_display_name - audit_action - action - actor_display_name - auditable_display_name - remote_ip - created_at - updated_at - metadata additionalProperties: false required: - has_next - has_prev - cursor_start - cursor_end - data "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |+ ### Authorization A service token must have at least one of the following access in order to use this API endpoint: **Service Token Accesses** `read_audit_logs` /organizations/{name}/cluster-size-skus: get: tags: - Organizations operationId: list_cluster_size_skus summary: List available cluster sizes parameters: - name: name in: path required: true description: The name of the organization 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: &a37 type: object properties: current_page: type: number description: The current page number next_page: type: number description: The next page number next_page_url: type: string description: The next page of results prev_page: type: number description: The previous page number prev_page_url: type: string description: The previous page of results data: type: array items: type: object properties: name: type: string description: The name of the cluster SKU display_name: type: string description: The display name cpu: type: number description: The number of CPUs storage: type: number description: The amount of storage in bytes ram: type: number 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) sort_order: type: number description: The sort order of the cluster SKU additionalProperties: false required: - name - display_name - cpu - storage - ram - metal - enabled - provider - sort_order 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 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/{name}/regions: get: tags: - Organizations operationId: list_regions_for_organization summary: List regions for an organization parameters: - name: name in: path required: true description: The name of the organization schema: type: string - name: page in: query description: If provided, specifies the page offset of returned results schema: type: number default: 1 - name: per_page in: query description: If provided, specifies the number of returned results schema: type: number default: 25 responses: "200": description: Returns the organization's regions headers: {} content: application/json: schema: &a17 type: object properties: current_page: type: number description: The current page number next_page: type: number description: The next page number next_page_url: type: string description: The next page of results prev_page: type: number description: The previous page number prev_page_url: type: string description: The previous page of results data: type: array items: type: object properties: id: type: string description: The ID of the 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_name}/teams: get: tags: - Organization teams operationId: list_organization_teams summary: List teams in an organization parameters: - name: organization_name 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: &a56 type: object properties: current_page: type: number description: The current page number next_page: type: number description: The next page number next_page_url: type: string description: The next page of results prev_page: type: number description: The previous page number prev_page_url: type: string description: The previous page of results data: type: array items: type: object properties: id: type: string description: The ID of the 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_name 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: &a2 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_organization` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_organization` | /organizations/{organization_name}/teams/{team_slug}: get: tags: - Organization teams operationId: get_organization_team summary: Get an organization team parameters: - name: organization_name in: path required: true description: The name of the organization schema: type: string - name: team_slug 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: *a2 "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_name in: path required: true description: The name of the organization schema: type: string - name: team_slug 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: *a2 "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_organization` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_organization` | delete: tags: - Organization teams operationId: delete_organization_team summary: Delete an organization team parameters: - name: organization_name in: path required: true description: The name of the organization schema: type: string - name: team_slug 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_organization` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_organization` | /organizations/{organization}/databases: get: tags: - Databases operationId: list_databases summary: List databases parameters: - name: organization in: path required: true description: The name of the organization the database belongs to schema: type: string - name: q in: query description: Search term to filter databases by name schema: type: string - name: page in: query description: If provided, specifies the page offset of returned results schema: type: number default: 1 - name: per_page in: query description: If provided, specifies the number of returned results schema: type: number default: 25 responses: "200": description: Retrieves the databases for an organization headers: {} content: application/json: schema: &a30 type: object properties: current_page: type: number description: The current page number next_page: type: number description: The next page number next_page_url: type: string description: The next page of results prev_page: type: number description: The previous page number prev_page_url: type: string description: The previous page of results data: type: array items: type: object properties: id: type: string description: The ID of the database url: type: string description: The URL to the database API endpoint branches_url: type: string description: The URL to retrieve this database's branches via the API branches_count: type: number description: The total number of database branches open_schema_recommendations_count: type: number description: The total number of schema recommendations development_branches_count: type: number description: The total number of database development branches production_branches_count: type: number description: The total number of database production branches issues_count: type: number description: The total number of ongoing issues within a database multiple_admins_required_for_deletion: type: boolean description: If the database requires multiple admins for deletion ready: type: boolean description: If the database is ready to be used at_backup_restore_branches_limit: type: boolean description: If the database has reached its backup restored branch limit at_development_branch_usage_limit: type: boolean description: If the database has reached its development branch limit data_import: type: object properties: state: type: string description: State of the data import import_check_errors: type: string description: Errors encountered during the import check started_at: type: string description: When the import started finished_at: type: string description: When the import finished data_source: type: object properties: hostname: type: string description: Hostname of the data source port: type: number description: Port of the data source database: type: string description: Database name of the data source additionalProperties: false required: - hostname - port - database additionalProperties: false required: - state - import_check_errors - started_at - finished_at - data_source region: type: object properties: id: type: string description: The ID of the region provider: type: string description: Provider for the region (ex. AWS) enabled: type: boolean description: Whether or not the region is currently active public_ip_addresses: items: type: string type: array description: Public IP addresses for the region display_name: type: string description: Name of the region location: type: string description: Location of the region slug: type: string description: The slug of the region current_default: type: boolean description: True if the region is the default for new branch creation additionalProperties: false required: - id - provider - enabled - public_ip_addresses - display_name - location - slug - current_default html_url: type: string description: The URL to see this database's branches in the web UI name: type: string description: Name of the database state: type: string enum: - pending - importing - sleep_in_progress - sleeping - awakening - import_ready - ready description: State of the database sharded: type: boolean description: If the database is sharded default_branch_shard_count: type: number description: Number of shards in the default branch default_branch_read_only_regions_count: type: number description: Number of read only regions in the default branch default_branch_table_count: type: number description: Number of tables in the default branch schema default_branch: type: string description: The default branch for the database require_approval_for_deploy: type: boolean description: Whether an approval is required to deploy schema changes to this database resizing: type: boolean description: True if a branch is currently resizing resize_queued: type: boolean description: True if a branch has a queued resize request allow_data_branching: type: boolean description: Whether seeding branches with data is enabled for all branches foreign_keys_enabled: type: boolean description: Whether foreign key constraints are enabled automatic_migrations: type: boolean description: Whether to automatically manage Rails migrations during deploy requests restrict_branch_region: type: boolean description: Whether to restrict branch creation to one region insights_raw_queries: type: boolean description: Whether raw SQL queries are collected plan: type: string description: The database plan insights_enabled: type: boolean description: True if query insights is enabled for the database production_branch_web_console: type: boolean description: Whether web console is enabled for production branches migration_table_name: type: string description: Table name to use for copying schema migration data migration_framework: type: string description: Framework used for applying migrations created_at: type: string description: When the database was created updated_at: type: string description: When the database was last updated schema_last_updated_at: type: string description: When the default branch schema was last changed. kind: type: string enum: - mysql - postgresql description: The kind of database additionalProperties: false required: - id - url - branches_url - branches_count - open_schema_recommendations_count - development_branches_count - production_branches_count - issues_count - multiple_admins_required_for_deletion - ready - at_backup_restore_branches_limit - at_development_branch_usage_limit - data_import - region - html_url - name - state - sharded - default_branch_shard_count - default_branch_read_only_regions_count - default_branch_table_count - default_branch - require_approval_for_deploy - resizing - resize_queued - allow_data_branching - foreign_keys_enabled - automatic_migrations - restrict_branch_region - insights_raw_queries - plan - insights_enabled - production_branch_web_console - migration_table_name - migration_framework - created_at - updated_at - schema_last_updated_at - kind additionalProperties: false required: - current_page - next_page - next_page_url - prev_page - prev_page_url - data "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_database`, `delete_database`, `write_database`, `read_branch`, `delete_branch`, `create_branch`, `delete_production_branch`, `connect_branch`, `connect_production_branch`, `delete_branch_password`, `delete_production_branch_password`, `read_deploy_request`, `create_deploy_request`, `approve_deploy_request`, `read_schema_recommendations`, `close_schema_recommendations`, `read_comment`, `create_comment`, `restore_backup`, `restore_production_branch_backup`, `read_backups`, `write_backups`, `delete_backups`, `delete_production_branch_backups`, `write_branch_vschema`, `write_production_branch_vschema` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `read_databases` | post: tags: - Databases operationId: create_database summary: Create a database parameters: - name: organization in: path required: true description: The name of the organization the database belongs to schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: Name of the database region: type: string description: The region the database will be deployed in. If left blank, defaults to the organization's default region. cluster_size: type: string description: The database cluster size 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 kind: type: string enum: - mysql - postgresql description: The kind of database to create. additionalProperties: false required: - name - cluster_size responses: "201": description: Returns the created database headers: {} content: application/json: schema: &a16 type: object properties: id: type: string description: The ID of the database url: type: string description: The URL to the database API endpoint branches_url: type: string description: The URL to retrieve this database's branches via the API branches_count: type: number description: The total number of database branches open_schema_recommendations_count: type: number description: The total number of schema recommendations development_branches_count: type: number description: The total number of database development branches production_branches_count: type: number description: The total number of database production branches issues_count: type: number description: The total number of ongoing issues within a database multiple_admins_required_for_deletion: type: boolean description: If the database requires multiple admins for deletion ready: type: boolean description: If the database is ready to be used at_backup_restore_branches_limit: type: boolean description: If the database has reached its backup restored branch limit at_development_branch_usage_limit: type: boolean description: If the database has reached its development branch limit data_import: type: object properties: state: type: string description: State of the data import import_check_errors: type: string description: Errors encountered during the import check started_at: type: string description: When the import started finished_at: type: string description: When the import finished data_source: type: object properties: hostname: type: string description: Hostname of the data source port: type: number description: Port of the data source database: type: string description: Database name of the data source additionalProperties: false required: - hostname - port - database additionalProperties: false required: - state - import_check_errors - started_at - finished_at - data_source region: type: object properties: id: type: string description: The ID of the region provider: type: string description: Provider for the region (ex. AWS) enabled: type: boolean description: Whether or not the region is currently active public_ip_addresses: items: type: string type: array description: Public IP addresses for the region display_name: type: string description: Name of the region location: type: string description: Location of the region slug: type: string description: The slug of the region current_default: type: boolean description: True if the region is the default for new branch creation additionalProperties: false required: - id - provider - enabled - public_ip_addresses - display_name - location - slug - current_default html_url: type: string description: The URL to see this database's branches in the web UI name: type: string description: Name of the database state: type: string enum: - pending - importing - sleep_in_progress - sleeping - awakening - import_ready - ready description: State of the database sharded: type: boolean description: If the database is sharded default_branch_shard_count: type: number description: Number of shards in the default branch default_branch_read_only_regions_count: type: number description: Number of read only regions in the default branch default_branch_table_count: type: number description: Number of tables in the default branch schema default_branch: type: string description: The default branch for the database require_approval_for_deploy: type: boolean description: Whether an approval is required to deploy schema changes to this database resizing: type: boolean description: True if a branch is currently resizing resize_queued: type: boolean description: True if a branch has a queued resize request allow_data_branching: type: boolean description: Whether seeding branches with data is enabled for all branches foreign_keys_enabled: type: boolean description: Whether foreign key constraints are enabled automatic_migrations: type: boolean description: Whether to automatically manage Rails migrations during deploy requests restrict_branch_region: type: boolean description: Whether to restrict branch creation to one region insights_raw_queries: type: boolean description: Whether raw SQL queries are collected plan: type: string description: The database plan insights_enabled: type: boolean description: True if query insights is enabled for the database production_branch_web_console: type: boolean description: Whether web console is enabled for production branches migration_table_name: type: string description: Table name to use for copying schema migration data migration_framework: type: string description: Framework used for applying migrations created_at: type: string description: When the database was created updated_at: type: string description: When the database was last updated schema_last_updated_at: type: string description: When the default branch schema was last changed. kind: type: string enum: - mysql - postgresql description: The kind of database additionalProperties: false required: - id - url - branches_url - branches_count - open_schema_recommendations_count - development_branches_count - production_branches_count - issues_count - multiple_admins_required_for_deletion - ready - at_backup_restore_branches_limit - at_development_branch_usage_limit - data_import - region - html_url - name - state - sharded - default_branch_shard_count - default_branch_read_only_regions_count - default_branch_table_count - default_branch - require_approval_for_deploy - resizing - resize_queued - allow_data_branching - foreign_keys_enabled - automatic_migrations - restrict_branch_region - insights_raw_queries - plan - insights_enabled - production_branch_web_console - migration_table_name - migration_framework - created_at - updated_at - schema_last_updated_at - kind "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `create_databases` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `create_databases` | /organizations/{organization}/databases/{database_name}/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_name in: path required: true description: The name of the database schema: type: string - name: page in: query description: If provided, specifies the page offset of returned results schema: type: number default: 1 - name: per_page in: query description: If provided, specifies the number of returned results schema: type: number default: 25 responses: "200": description: Returns IP restriction entries for the database headers: {} content: application/json: schema: &a29 type: object properties: current_page: type: number description: The current page number next_page: type: number description: The next page number next_page_url: type: string description: The next page of results prev_page: type: number description: The previous page number prev_page_url: type: string description: The previous page of results data: type: array items: type: object properties: id: type: string description: The ID of the 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 OAuth token must have at least one of the following scopes in order to use this API endpoint: **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_name 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: &a3 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 OAuth token must have at least one of the following scopes in order to use this API endpoint: **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_databases` | | Database | `write_database` | /organizations/{organization}/databases/{database_name}/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_name 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: *a3 "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 OAuth token must have at least one of the following scopes in order to use this API endpoint: **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_name 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: *a3 "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 OAuth token must have at least one of the following scopes in order to use this API endpoint: **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_name 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 OAuth token must have at least one of the following scopes in order to use this API endpoint: **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_databases` | | Database | `write_database` | /organizations/{organization}/databases/{database}/branches: get: tags: - Database branches operationId: list_branches summary: List branches parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: q in: query description: Search branches by name schema: type: string - name: production in: query description: Filter branches by production status schema: type: boolean - name: safe_migrations in: query description: Filter branches by safe migrations (DDL protection) schema: type: boolean - name: order in: query description: Order branches by created_at time schema: type: string enum: - asc - desc - name: page in: query description: If provided, specifies the page offset of returned results schema: type: number default: 1 - name: per_page in: query description: If provided, specifies the number of returned results schema: type: number default: 25 responses: "200": description: Returns database branches headers: {} content: application/json: schema: &a23 type: object properties: current_page: type: number description: The current page number next_page: type: number description: The next page number next_page_url: type: string description: The next page of results prev_page: type: number description: The previous page number prev_page_url: type: string description: The previous page of results data: type: array items: type: object properties: id: type: string description: The ID of the branch name: type: string description: The name of the branch created_at: type: string description: When the branch was created updated_at: type: string description: When the branch was last updated deleted_at: type: string description: When the branch was deleted restore_checklist_completed_at: type: string description: When a user last marked a backup restore checklist as completed schema_last_updated_at: type: string description: When the schema for the branch was last updated kind: type: string enum: - mysql - postgresql description: The kind of branch mysql_address: type: string description: The MySQL address for the branch mysql_edge_address: type: string description: The address of the MySQL provider for the branch state: type: string enum: - pending - sleep_in_progress - sleeping - awakening - ready description: The current state of the branch direct_vtgate: type: boolean description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers vtgate_size: type: string description: The size of the vtgate cluster for the branch vtgate_count: type: number description: The number of vtgate instances in the branch cluster_name: type: string description: The SKU representing the branch's cluster size cluster_iops: type: number description: IOPS for the cluster ready: type: boolean description: Whether or not the branch is ready to serve queries schema_ready: type: boolean description: Whether or not the schema is ready for queries metal: type: boolean description: Whether or not this is a metal database production: type: boolean description: Whether or not the branch is a production branch safe_migrations: type: boolean description: Whether or not the branch has safe migrations enabled sharded: type: boolean description: Whether or not the branch is sharded shard_count: type: number description: The number of shards in the branch stale_schema: type: boolean description: Whether or not the branch has a stale schema actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url restored_from_branch: type: object properties: id: type: string description: The ID for the resource name: type: string description: The name for the resource created_at: type: string description: When the resource was created updated_at: type: string description: When the resource was last updated deleted_at: type: string description: When the resource was deleted, if deleted additionalProperties: false required: - id - name - created_at - updated_at - deleted_at private_edge_connectivity: type: boolean description: True if private connections are enabled has_replicas: type: boolean description: True if the branch has replica servers has_read_only_replicas: type: boolean description: True if the branch has read-only replica servers html_url: type: string description: Planetscale app URL for the branch url: type: string description: Planetscale API URL for the branch region: type: object properties: id: type: string description: The ID of the region provider: type: string description: Provider for the region (ex. AWS) enabled: type: boolean description: Whether or not the region is currently active public_ip_addresses: items: type: string type: array description: Public IP addresses for the region display_name: type: string description: Name of the region location: type: string description: Location of the region slug: type: string description: The slug of the region current_default: type: boolean description: True if the region is the default for new branch creation additionalProperties: false required: - id - provider - enabled - public_ip_addresses - display_name - location - slug - current_default parent_branch: type: string description: The name of the parent branch from which the branch was created additionalProperties: false required: - id - name - created_at - updated_at - deleted_at - restore_checklist_completed_at - schema_last_updated_at - kind - mysql_address - mysql_edge_address - state - direct_vtgate - vtgate_size - vtgate_count - cluster_name - cluster_iops - ready - schema_ready - metal - production - safe_migrations - sharded - shard_count - stale_schema - actor - restored_from_branch - private_edge_connectivity - has_replicas - has_read_only_replicas - html_url - url - region - parent_branch additionalProperties: false required: - current_page - next_page - next_page_url - prev_page - prev_page_url - data "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `read_branches` | | Database | `read_branches` | | Branch | `read_branch` | post: tags: - Database branches operationId: create_branch summary: Create a branch parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: The name of the branch parent_branch: type: string description: Parent branch backup_id: type: string description: If provided, restores the backup's schema and data to the new branch. Must have `restore_production_branch_backup(s)` or `restore_backup(s)` access to do this. region: type: string description: The region to create the branch in. If not provided, the branch will be created in the default region for its database. restore_point: type: string description: Restore from a point-in-time recovery timestamp (e.g. 2023-01-01T00:00:00Z). Available only for PostgreSQL databases. seed_data: type: string enum: - last_successful_backup description: If provided, restores the last successful backup's schema and data to the new branch. Must have `restore_production_branch_backup(s)` or `restore_backup(s)` access to do this, in addition to Data Branching™ being enabled for the branch. cluster_size: type: string description: "The database cluster size is required if a backup_id is provided. Options: PS_10, PS_20, PS_40, ..., PS_2800" additionalProperties: false required: - name - parent_branch responses: "201": description: Returns the created branch headers: {} content: application/json: schema: &a11 type: object properties: id: type: string description: The ID of the branch name: type: string description: The name of the branch created_at: type: string description: When the branch was created updated_at: type: string description: When the branch was last updated deleted_at: type: string description: When the branch was deleted restore_checklist_completed_at: type: string description: When a user last marked a backup restore checklist as completed schema_last_updated_at: type: string description: When the schema for the branch was last updated kind: type: string enum: - mysql - postgresql description: The kind of branch mysql_address: type: string description: The MySQL address for the branch mysql_edge_address: type: string description: The address of the MySQL provider for the branch state: type: string enum: - pending - sleep_in_progress - sleeping - awakening - ready description: The current state of the branch direct_vtgate: type: boolean description: True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers vtgate_size: type: string description: The size of the vtgate cluster for the branch vtgate_count: type: number description: The number of vtgate instances in the branch cluster_name: type: string description: The SKU representing the branch's cluster size cluster_iops: type: number description: IOPS for the cluster ready: type: boolean description: Whether or not the branch is ready to serve queries schema_ready: type: boolean description: Whether or not the schema is ready for queries metal: type: boolean description: Whether or not this is a metal database production: type: boolean description: Whether or not the branch is a production branch safe_migrations: type: boolean description: Whether or not the branch has safe migrations enabled sharded: type: boolean description: Whether or not the branch is sharded shard_count: type: number description: The number of shards in the branch stale_schema: type: boolean description: Whether or not the branch has a stale schema actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url restored_from_branch: type: object properties: id: type: string description: The ID for the resource name: type: string description: The name for the resource created_at: type: string description: When the resource was created updated_at: type: string description: When the resource was last updated deleted_at: type: string description: When the resource was deleted, if deleted additionalProperties: false required: - id - name - created_at - updated_at - deleted_at private_edge_connectivity: type: boolean description: True if private connections are enabled has_replicas: type: boolean description: True if the branch has replica servers has_read_only_replicas: type: boolean description: True if the branch has read-only replica servers html_url: type: string description: Planetscale app URL for the branch url: type: string description: Planetscale API URL for the branch region: type: object properties: id: type: string description: The ID of the region provider: type: string description: Provider for the region (ex. AWS) enabled: type: boolean description: Whether or not the region is currently active public_ip_addresses: items: type: string type: array description: Public IP addresses for the region display_name: type: string description: Name of the region location: type: string description: Location of the region slug: type: string description: The slug of the region current_default: type: boolean description: True if the region is the default for new branch creation additionalProperties: false required: - id - provider - enabled - public_ip_addresses - display_name - location - slug - current_default parent_branch: type: string description: The name of the parent branch from which the branch was created additionalProperties: false required: - id - name - created_at - updated_at - deleted_at - restore_checklist_completed_at - schema_last_updated_at - kind - mysql_address - mysql_edge_address - state - direct_vtgate - vtgate_size - vtgate_count - cluster_name - cluster_iops - ready - schema_ready - metal - production - safe_migrations - sharded - shard_count - stale_schema - actor - restored_from_branch - private_edge_connectivity - has_replicas - has_read_only_replicas - html_url - url - region - parent_branch "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `create_branch`, `restore_production_branch_backup`, `restore_backup` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_branches`, `restore_production_branch_backups`, `restore_backups` | | Database | `write_branches`, `restore_production_branch_backups`, `restore_backups` | | Branch | `restore_backups` | /organizations/{organization}/databases/{database}/branches/{branch}/backups: get: tags: - Backups operationId: list_backups summary: List backups parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: branch in: path required: true description: The name of the branch schema: type: string - name: all in: query description: Whether to include all backups, including deleted ones schema: type: boolean - name: state in: query description: Filter backups by state schema: type: string enum: - pending - running - success - failed - canceled - ignored - name: policy in: query description: Filter backups by backup policy ID schema: type: string - name: from in: query description: Filter backups started after this date (e.g. 2023-01-01T00:00:00Z) schema: type: string - name: to in: query description: Filter backups started before this date (e.g. 2023-01-31T23:59:59Z) schema: type: string - name: running_at in: query description: Filter backups that are running during a specific time (e.g. 2023-01-01T00:00:00Z..2023-01-01T23:59:59Z) schema: type: string - name: production in: query description: Filter backups by production branch schema: type: boolean - name: page in: query description: If provided, specifies the page offset of returned results schema: type: number default: 1 - name: per_page in: query description: If provided, specifies the number of returned results schema: type: number default: 25 responses: "200": description: Returns database branch backups headers: {} content: application/json: schema: &a20 type: object properties: current_page: type: number description: The current page number next_page: type: number description: The next page number next_page_url: type: string description: The next page of results prev_page: type: number description: The previous page number prev_page_url: type: string description: The previous page of results data: type: array items: type: object properties: id: type: string description: The ID of the backup name: type: string description: The name of the backup state: type: string enum: - pending - running - success - failed - canceled - ignored description: The current state of the backup size: type: number description: The size of the backup in bytes estimated_storage_cost: type: number description: The estimated storage cost of the backup created_at: type: string description: When the backup was created updated_at: type: string description: When the backup was last updated started_at: type: string description: When the backup started expires_at: type: string description: When the backup expires completed_at: type: string description: When the backup completed deleted_at: type: string description: When the backup was deleted pvc_size: type: number description: Size of the PVC used for the backup protected: type: boolean description: Whether or not the backup is protected from deletion required: type: boolean description: Whether or not the backup policy is required restored_branches: type: array items: type: object properties: id: type: string description: The ID for the resource name: type: string description: The name for the resource created_at: type: string description: When the resource was created updated_at: type: string description: When the resource was last updated deleted_at: type: string description: When the resource was deleted, if deleted additionalProperties: false required: - id - name - created_at - updated_at - deleted_at actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url backup_policy: type: object properties: id: type: string description: The ID of the backup policy name: type: string description: The name of the backup policy target: type: string enum: - production - development description: Whether the policy is for production or development branches retention_value: type: number description: A number value for the retention period of the backup policy retention_unit: type: string description: The unit for the retention period of the backup policy frequency_value: type: number description: A number value for the frequency of the backup policy frequency_unit: type: string description: The unit for the frequency of the backup policy schedule_time: type: string description: The time of day that the backup is scheduled, in HH:MM format schedule_day: type: string enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 description: Day of the week that the backup is scheduled schedule_week: type: string enum: - 0 - 1 - 2 - 3 description: Week of the month that the backup is scheduled created_at: type: string description: When the backup policy was created updated_at: type: string description: When the backup policy was last updated last_ran_at: type: string description: When the backup was last run next_run_at: type: string description: When the backup will next run required: type: boolean description: Whether the policy is a required system backup additionalProperties: false required: - id - name - target - retention_value - retention_unit - frequency_value - frequency_unit - schedule_time - schedule_day - schedule_week - created_at - updated_at - last_ran_at - next_run_at - required schema_snapshot: type: object properties: id: type: string description: The ID of the schema snapshot name: type: string description: The name of the schema snapshot created_at: type: string description: When the schema snapshot was created updated_at: type: string description: When the schema snapshot was last updated linted_at: type: string description: When the schema snapshot was last linted url: type: string description: The URL to the schema snapshot in the PlanetScale app additionalProperties: false required: - id - name - created_at - updated_at - linted_at - url database_branch: type: object properties: id: type: string description: The ID for the resource name: type: string description: The name for the resource created_at: type: string description: When the resource was created updated_at: type: string description: When the resource was last updated deleted_at: type: string description: When the resource was deleted, if deleted additionalProperties: false required: - id - name - created_at - updated_at - deleted_at additionalProperties: false required: - id - name - state - size - estimated_storage_cost - created_at - updated_at - started_at - expires_at - completed_at - deleted_at - pvc_size - protected - required - restored_branches - actor - backup_policy - schema_snapshot - database_branch additionalProperties: false required: - current_page - next_page - next_page_url - prev_page - prev_page_url - data "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_backups` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `read_backups` | | Database | `read_backups` | | Branch | `read_backups` | post: tags: - Backups operationId: create_backup summary: Create a backup parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: branch in: path required: true description: The name of the branch schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: Name for the backup retention_unit: type: string enum: - hour - day - week - month - year description: Unit for the retention period of the backup retention_value: type: number description: Value between `1`` and `1000`` for the retention period of the backup (i.e retention_value `6`` and retention_unit `hour` means 6 hours) emergency: type: boolean description: Whether the backup is an immediate backup that may affect database performance. Emergency backups are only supported for PostgreSQL databases. additionalProperties: false responses: "201": description: Returns the created database branch backup headers: {} content: application/json: schema: &a4 type: object properties: id: type: string description: The ID of the backup name: type: string description: The name of the backup state: type: string enum: - pending - running - success - failed - canceled - ignored description: The current state of the backup size: type: number description: The size of the backup in bytes estimated_storage_cost: type: number description: The estimated storage cost of the backup created_at: type: string description: When the backup was created updated_at: type: string description: When the backup was last updated started_at: type: string description: When the backup started expires_at: type: string description: When the backup expires completed_at: type: string description: When the backup completed deleted_at: type: string description: When the backup was deleted pvc_size: type: number description: Size of the PVC used for the backup protected: type: boolean description: Whether or not the backup is protected from deletion required: type: boolean description: Whether or not the backup policy is required restored_branches: type: array items: type: object properties: id: type: string description: The ID for the resource name: type: string description: The name for the resource created_at: type: string description: When the resource was created updated_at: type: string description: When the resource was last updated deleted_at: type: string description: When the resource was deleted, if deleted additionalProperties: false required: - id - name - created_at - updated_at - deleted_at actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url backup_policy: type: object properties: id: type: string description: The ID of the backup policy name: type: string description: The name of the backup policy target: type: string enum: - production - development description: Whether the policy is for production or development branches retention_value: type: number description: A number value for the retention period of the backup policy retention_unit: type: string description: The unit for the retention period of the backup policy frequency_value: type: number description: A number value for the frequency of the backup policy frequency_unit: type: string description: The unit for the frequency of the backup policy schedule_time: type: string description: The time of day that the backup is scheduled, in HH:MM format schedule_day: type: string enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 description: Day of the week that the backup is scheduled schedule_week: type: string enum: - 0 - 1 - 2 - 3 description: Week of the month that the backup is scheduled created_at: type: string description: When the backup policy was created updated_at: type: string description: When the backup policy was last updated last_ran_at: type: string description: When the backup was last run next_run_at: type: string description: When the backup will next run required: type: boolean description: Whether the policy is a required system backup additionalProperties: false required: - id - name - target - retention_value - retention_unit - frequency_value - frequency_unit - schedule_time - schedule_day - schedule_week - created_at - updated_at - last_ran_at - next_run_at - required schema_snapshot: type: object properties: id: type: string description: The ID of the schema snapshot name: type: string description: The name of the schema snapshot created_at: type: string description: When the schema snapshot was created updated_at: type: string description: When the schema snapshot was last updated linted_at: type: string description: When the schema snapshot was last linted url: type: string description: The URL to the schema snapshot in the PlanetScale app additionalProperties: false required: - id - name - created_at - updated_at - linted_at - url database_branch: type: object properties: id: type: string description: The ID for the resource name: type: string description: The name for the resource created_at: type: string description: When the resource was created updated_at: type: string description: When the resource was last updated deleted_at: type: string description: When the resource was deleted, if deleted additionalProperties: false required: - id - name - created_at - updated_at - deleted_at additionalProperties: false required: - id - name - state - size - estimated_storage_cost - created_at - updated_at - started_at - expires_at - completed_at - deleted_at - pvc_size - protected - required - restored_branches - actor - backup_policy - schema_snapshot - database_branch "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `write_backups` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_backups` | | Database | `write_backups` | | Branch | `write_backups` | /organizations/{organization}/databases/{database}/branches/{branch}/backups/{id}: get: tags: - Backups operationId: get_backup summary: Get a backup parameters: - name: id in: path required: true description: The ID for the backup schema: type: string - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: branch in: path required: true description: The name of the branch schema: type: string responses: "200": description: Returns a database branch backup headers: {} content: application/json: schema: *a4 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_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: *a4 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `write_backups` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_backups` | | Database | `write_backups` | | Branch | `write_backups` | delete: tags: - Backups operationId: delete_backup summary: Delete a backup parameters: - name: id in: path required: true description: The ID of the backup schema: type: string - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: branch in: path required: true description: The name of the branch schema: type: string responses: "204": description: Delete a backup headers: {} "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `delete_backups`, `delete_production_branch_backups` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `delete_backups`, `delete_production_branch_backups` | | Database | `delete_backups`, `delete_production_branch_backups` | | Branch | `delete_backups` | /organizations/{organization}/databases/{database}/branches/{branch}/bouncer-resizes: get: tags: - api-branch_bouncer_resizes operationId: list_branch_bouncer_resize_requests summary: Get bouncer resize requests parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string - name: page in: query description: If provided, specifies the page offset of returned results schema: type: number default: 1 - name: per_page in: query description: If provided, specifies the number of returned results schema: type: number default: 25 responses: "200": description: Returns bouncer resize requests headers: {} content: application/json: schema: &a6 type: object properties: current_page: type: number description: The current page number next_page: type: number description: The next page number next_page_url: type: string description: The next page of results prev_page: type: number description: The previous page number prev_page_url: type: string description: The previous page of results data: type: array items: type: object properties: id: type: string description: The ID of the bouncer resize state: type: string enum: - pending - resizing - canceled - completed description: The state of the bouncer resize replicas_per_cell: type: number description: The number of replicas per cell for the bouncer after the resize parameters: type: object additionalProperties: true description: The bouncer parameters previous_replicas_per_cell: type: number description: The number of replicas per cell for the bouncer before the resize previous_parameters: type: object additionalProperties: true description: The previous bouncer parameters started_at: type: string description: The time the bouncer resize started completed_at: type: string description: The time the bouncer resize completed created_at: type: string description: The time the bouncer resize was created updated_at: type: string description: The time the bouncer resize was last updated actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url bouncer: type: object properties: id: type: string description: The ID for the resource name: type: string description: The name for the resource created_at: type: string description: When the resource was created updated_at: type: string description: When the resource was last updated deleted_at: type: string description: When the resource was deleted, if deleted additionalProperties: false required: - id - name - created_at - updated_at - deleted_at sku: type: object properties: name: type: string description: The name of the Postgres bouncer SKU display_name: type: string description: The display name cpu: type: string description: The CPU allocation ram: type: number description: The amount of memory in bytes sort_order: type: number description: The sort order of the Postgres bouncer SKU additionalProperties: false required: - name - display_name - cpu - ram - sort_order previous_sku: type: object properties: name: type: string description: The name of the Postgres bouncer SKU display_name: type: string description: The display name cpu: type: string description: The CPU allocation ram: type: number description: The amount of memory in bytes sort_order: type: number description: The sort order of the Postgres bouncer SKU additionalProperties: false required: - name - display_name - cpu - ram - sort_order additionalProperties: false required: - id - state - replicas_per_cell - parameters - previous_replicas_per_cell - previous_parameters - started_at - completed_at - created_at - updated_at - actor - bouncer - sku - previous_sku additionalProperties: false required: - current_page - next_page - next_page_url - prev_page - prev_page_url - data "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `read_branches` | | Database | `read_branches` | | Branch | `read_branch` | /organizations/{organization}/databases/{database}/branches/{branch}/bouncers: get: tags: - Bouncers operationId: list_bouncers summary: List bouncers parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string - name: page in: query description: If provided, specifies the page offset of returned results schema: type: number default: 1 - name: per_page in: query description: If provided, specifies the number of returned results schema: type: number default: 25 responses: "200": description: Returns bouncers headers: {} content: application/json: schema: &a40 type: object properties: current_page: type: number description: The current page number next_page: type: number description: The next page number next_page_url: type: string description: The next page of results prev_page: type: number description: The previous page number prev_page_url: type: string description: The previous page of results data: type: array items: type: object properties: id: type: string description: The ID of the 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: number description: The amount of memory in bytes sort_order: type: number description: The sort order of the Postgres bouncer SKU additionalProperties: false required: - name - display_name - cpu - ram - sort_order target: type: string enum: - primary - replica - replica_az_affinity description: The instance type the bouncer targets replicas_per_cell: type: number description: The count of replicas in each cell created_at: type: string description: When the bouncer was created updated_at: type: string description: When the bouncer was updated deleted_at: type: string description: When the bouncer was deleted actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url branch: type: object properties: id: type: string description: The ID for the resource name: type: string description: The name for the resource created_at: type: string description: When the resource was created updated_at: type: string description: When the resource was last updated deleted_at: type: string description: When the resource was deleted, if deleted additionalProperties: false required: - id - name - created_at - updated_at - deleted_at parameters: type: array items: type: object properties: id: type: string description: The ID of the parameter namespace: type: string enum: - pgbouncer description: The namespace of the parameter name: type: string description: The name of the parameter display_name: type: string description: The display name of the parameter category: type: string description: The category of the parameter description: type: string description: The description of the parameter parameter_type: type: string enum: - array - boolean - bytes - float - integer - internal - milliseconds - seconds - select - string - time description: The type of the parameter default_value: type: string description: The default value of the parameter value: type: string description: The configured value of the parameter required: type: boolean description: Whether the parameter is required created_at: type: string description: When the parameter was created updated_at: type: string description: When the parameter was last updated restart: type: boolean description: True if processes require a server restart on change max: type: number description: The maximum value of the parameter min: type: number description: The minimum value of the parameter step: type: number description: The step change of the parameter url: type: string description: The URL of the parameter options: items: type: string type: array description: Valid options for the parameter value actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url additionalProperties: false required: - id - namespace - name - display_name - category - description - parameter_type - default_value - value - required - created_at - updated_at - restart - max - min - step - url - options - actor additionalProperties: false required: - id - name - 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: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: The bouncer name target: type: string description: The type of server the bouncer targets bouncer_size: type: string description: The size SKU for the bouncer replicas_per_cell: type: number description: The number of replica servers per cell additionalProperties: false responses: "200": description: Returns the new bouncer headers: {} content: application/json: schema: &a5 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: number description: The amount of memory in bytes sort_order: type: number description: The sort order of the Postgres bouncer SKU additionalProperties: false required: - name - display_name - cpu - ram - sort_order target: type: string enum: - primary - replica - replica_az_affinity description: The instance type the bouncer targets replicas_per_cell: type: number description: The count of replicas in each cell created_at: type: string description: When the bouncer was created updated_at: type: string description: When the bouncer was updated deleted_at: type: string description: When the bouncer was deleted actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url branch: type: object properties: id: type: string description: The ID for the resource name: type: string description: The name for the resource created_at: type: string description: When the resource was created updated_at: type: string description: When the resource was last updated deleted_at: type: string description: When the resource was deleted, if deleted additionalProperties: false required: - id - name - created_at - updated_at - deleted_at parameters: type: array items: type: object properties: id: type: string description: The ID of the parameter namespace: type: string enum: - pgbouncer description: The namespace of the parameter name: type: string description: The name of the parameter display_name: type: string description: The display name of the parameter category: type: string description: The category of the parameter description: type: string description: The description of the parameter parameter_type: type: string enum: - array - boolean - bytes - float - integer - internal - milliseconds - seconds - select - string - time description: The type of the parameter default_value: type: string description: The default value of the parameter value: type: string description: The configured value of the parameter required: type: boolean description: Whether the parameter is required created_at: type: string description: When the parameter was created updated_at: type: string description: When the parameter was last updated restart: type: boolean description: True if processes require a server restart on change max: type: number description: The maximum value of the parameter min: type: number description: The minimum value of the parameter step: type: number description: The step change of the parameter url: type: string description: The URL of the parameter options: items: type: string type: array description: Valid options for the parameter value actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url additionalProperties: false required: - id - namespace - name - display_name - category - description - parameter_type - default_value - value - required - created_at - updated_at - restart - max - min - step - url - options - actor additionalProperties: false required: - id - name - 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/{name}: get: tags: - Bouncers operationId: get_bouncer summary: Get a bouncer parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string - name: name in: path required: true description: The name of the bouncer schema: type: string responses: "200": description: Returns a bouncer headers: {} content: application/json: schema: *a5 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `read_branches` | | Database | `read_branches` | | Branch | `read_branch` | delete: tags: - Bouncers operationId: delete_bouncer summary: Delete a bouncer parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string - name: name in: path required: true description: The name of the bouncer schema: type: string responses: "204": description: Deletes the bouncer headers: {} "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `write_database` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_databases` | | Database | `write_database` | /organizations/{organization}/databases/{database}/branches/{branch}/bouncers/{name}/resizes: get: tags: - Bouncer resizes operationId: list_bouncer_resize_requests summary: Get bouncer resize requests parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string - name: name in: path required: true description: The name of the bouncer schema: type: string - name: page in: query description: If provided, specifies the page offset of returned results schema: type: number default: 1 - name: per_page in: query description: If provided, specifies the number of returned results schema: type: number default: 25 responses: "200": description: Returns bouncer resize requests headers: {} content: application/json: schema: *a6 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `read_branches` | | Database | `read_branches` | | Branch | `read_branch` | patch: tags: - Bouncer resizes operationId: update_bouncer_resize_request summary: Upsert a bouncer resize request parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string - name: name in: path required: true description: The name of the bouncer schema: type: string 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: number 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: &a39 type: object properties: id: type: string description: The ID of the bouncer resize state: type: string enum: - pending - resizing - canceled - completed description: The state of the bouncer resize replicas_per_cell: type: number description: The number of replicas per cell for the bouncer after the resize parameters: type: object additionalProperties: true description: The bouncer parameters previous_replicas_per_cell: type: number description: The number of replicas per cell for the bouncer before the resize previous_parameters: type: object additionalProperties: true description: The previous bouncer parameters started_at: type: string description: The time the bouncer resize started completed_at: type: string description: The time the bouncer resize completed created_at: type: string description: The time the bouncer resize was created updated_at: type: string description: The time the bouncer resize was last updated actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url bouncer: type: object properties: id: type: string description: The ID for the resource name: type: string description: The name for the resource created_at: type: string description: When the resource was created updated_at: type: string description: When the resource was last updated deleted_at: type: string description: When the resource was deleted, if deleted additionalProperties: false required: - id - name - created_at - updated_at - deleted_at sku: type: object properties: name: type: string description: The name of the Postgres bouncer SKU display_name: type: string description: The display name cpu: type: string description: The CPU allocation ram: type: number description: The amount of memory in bytes sort_order: type: number description: The sort order of the Postgres bouncer SKU additionalProperties: false required: - name - display_name - cpu - ram - sort_order previous_sku: type: object properties: name: type: string description: The name of the Postgres bouncer SKU display_name: type: string description: The display name cpu: type: string description: The CPU allocation ram: type: number description: The amount of memory in bytes sort_order: type: number description: The sort order of the Postgres bouncer SKU additionalProperties: false required: - name - display_name - cpu - ram - sort_order additionalProperties: false required: - id - state - replicas_per_cell - parameters - previous_replicas_per_cell - previous_parameters - started_at - completed_at - created_at - updated_at - actor - bouncer - sku - previous_sku "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `write_database` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_databases` | | Database | `write_database` | delete: tags: - Bouncer resizes operationId: cancel_bouncer_resize_request summary: Cancel a resize request parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string - name: name in: path required: true description: The name of the bouncer schema: type: string responses: "204": description: Cancels a resize request headers: {} "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `write_database` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_databases` | | Database | `write_database` | /organizations/{organization}/databases/{database}/branches/{branch}/changes: get: tags: - Branch changes operationId: list_branch_change_requests summary: Get branch change requests parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string - name: page in: query description: If provided, specifies the page offset of returned results schema: type: number default: 1 - name: per_page in: query description: If provided, specifies the number of returned results schema: type: number default: 25 responses: "200": description: Returns branch change requests headers: {} content: application/json: schema: &a21 type: object properties: current_page: type: number description: The current page number next_page: type: number description: The next page number next_page_url: type: string description: The next page of results prev_page: type: number description: The previous page number prev_page_url: type: string description: The previous page of results data: type: array items: type: object properties: id: type: string description: The ID of the branch change request restart: items: type: number type: array description: The ports requiring a restart when changes are applied state: type: string enum: - queued - pending - resizing - canceled - completed description: The state of the branch change request started_at: type: string description: The time the branch change request started completed_at: type: string description: The time the branch change request completed created_at: type: string description: The time the branch change request was created updated_at: type: string description: The time the branch change request was last updated actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url cluster_name: type: string description: The SKU representing the branch cluster cluster_display_name: type: string description: The SKU representing the branch cluster for display cluster_metal: type: boolean description: Whether or not this is a metal database replicas: type: number description: The total number of replicas parameters: type: object additionalProperties: true description: The branch parameters previous_cluster_name: type: string description: The previous SKU representing the branch cluster previous_cluster_display_name: type: string description: The previous SKU representing the branch cluster for display previous_cluster_metal: type: boolean description: Whether or not the previous SKU was a metal database previous_replicas: type: number description: The previous total number of replicas previous_parameters: type: object additionalProperties: true description: The previous branch parameters minimum_storage_bytes: type: number description: The minimum storage size in bytes maximum_storage_bytes: type: number description: The maximum storage size in bytes storage_autoscaling: type: boolean description: Whether storage autoscaling is enabled storage_shrinking: type: boolean description: Whether storage shrinking is enabled when autoscaling is enabled storage_type: type: string enum: - gp3 - io2 - pd_ssd description: The storage type (gp3 or io2) storage_iops: type: number description: The storage IOPS storage_throughput_mibs: type: number description: The storage throughput in MiB/s previous_minimum_storage_bytes: type: number description: The previous minimum storage size in bytes previous_maximum_storage_bytes: type: number description: The previous maximum storage size in bytes previous_storage_autoscaling: type: boolean description: Whether storage autoscaling was previously enabled previous_storage_shrinking: type: boolean description: Whether storage shrinking was previously enabled previous_storage_type: type: string description: The previous storage type previous_storage_iops: type: number description: The previous storage IOPS previous_storage_throughput_mibs: type: number description: The previous storage throughput in MiB/s additionalProperties: false required: - id - restart - state - started_at - completed_at - created_at - updated_at - actor - cluster_name - cluster_display_name - cluster_metal - replicas - parameters - previous_cluster_name - previous_cluster_display_name - previous_cluster_metal - previous_replicas - previous_parameters - minimum_storage_bytes - maximum_storage_bytes - storage_autoscaling - storage_shrinking - storage_type - storage_iops - storage_throughput_mibs - previous_minimum_storage_bytes - previous_maximum_storage_bytes - previous_storage_autoscaling - previous_storage_shrinking - previous_storage_type - previous_storage_iops - previous_storage_throughput_mibs additionalProperties: false required: - current_page - next_page - next_page_url - prev_page - prev_page_url - data "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `read_branches` | | Database | `read_branches` | | Branch | `read_branch` | patch: tags: - Branch changes operationId: update_branch_change_request summary: Upsert a change request parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string 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: number 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: &a22 type: object properties: id: type: string description: The ID of the branch change request restart: items: type: number type: array description: The ports requiring a restart when changes are applied state: type: string enum: - queued - pending - resizing - canceled - completed description: The state of the branch change request started_at: type: string description: The time the branch change request started completed_at: type: string description: The time the branch change request completed created_at: type: string description: The time the branch change request was created updated_at: type: string description: The time the branch change request was last updated actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url cluster_name: type: string description: The SKU representing the branch cluster cluster_display_name: type: string description: The SKU representing the branch cluster for display cluster_metal: type: boolean description: Whether or not this is a metal database replicas: type: number description: The total number of replicas parameters: type: object additionalProperties: true description: The branch parameters previous_cluster_name: type: string description: The previous SKU representing the branch cluster previous_cluster_display_name: type: string description: The previous SKU representing the branch cluster for display previous_cluster_metal: type: boolean description: Whether or not the previous SKU was a metal database previous_replicas: type: number description: The previous total number of replicas previous_parameters: type: object additionalProperties: true description: The previous branch parameters minimum_storage_bytes: type: number description: The minimum storage size in bytes maximum_storage_bytes: type: number description: The maximum storage size in bytes storage_autoscaling: type: boolean description: Whether storage autoscaling is enabled storage_shrinking: type: boolean description: Whether storage shrinking is enabled when autoscaling is enabled storage_type: type: string enum: - gp3 - io2 - pd_ssd description: The storage type (gp3 or io2) storage_iops: type: number description: The storage IOPS storage_throughput_mibs: type: number description: The storage throughput in MiB/s previous_minimum_storage_bytes: type: number description: The previous minimum storage size in bytes previous_maximum_storage_bytes: type: number description: The previous maximum storage size in bytes previous_storage_autoscaling: type: boolean description: Whether storage autoscaling was previously enabled previous_storage_shrinking: type: boolean description: Whether storage shrinking was previously enabled previous_storage_type: type: string description: The previous storage type previous_storage_iops: type: number description: The previous storage IOPS previous_storage_throughput_mibs: type: number description: The previous storage throughput in MiB/s additionalProperties: false required: - id - restart - state - started_at - completed_at - created_at - updated_at - actor - cluster_name - cluster_display_name - cluster_metal - replicas - parameters - previous_cluster_name - previous_cluster_display_name - previous_cluster_metal - previous_replicas - previous_parameters - minimum_storage_bytes - maximum_storage_bytes - storage_autoscaling - storage_shrinking - storage_type - storage_iops - storage_throughput_mibs - previous_minimum_storage_bytes - previous_maximum_storage_bytes - previous_storage_autoscaling - previous_storage_shrinking - previous_storage_type - previous_storage_iops - previous_storage_throughput_mibs "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `write_database` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_databases` | | Database | `write_database` | /organizations/{organization}/databases/{database}/branches/{branch}/extensions: get: tags: - Cluster extensions operationId: list_extensions summary: List cluster extensions parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string responses: "200": description: Returns cluster extensions headers: {} content: application/json: schema: type: array items: &a25 type: object properties: id: type: string description: The ID of the extension name: type: string description: The name of the extension description: type: string description: The description of the extension internal: type: boolean description: The internal state of the extension url: type: string description: The URL of the extension parameters: type: array items: type: object properties: id: type: string description: The ID of the parameter name: type: string description: The name of the parameter display_name: type: string description: The display name of the parameter namespace: type: string enum: - patroni - pgconf - pgbouncer description: The namespace of the parameter category: type: string description: The category of the parameter description: type: string description: The description of the parameter extension: type: boolean description: Configures an extension internal: type: boolean description: The internal state of the parameter parameter_type: type: string enum: - array - boolean - bytes - float - integer - internal - milliseconds - seconds - select - string - time description: The type of the parameter default_value: type: string description: The default value of the parameter value: type: string description: The configured value of the parameter required: type: boolean description: Whether the parameter is required created_at: type: string description: When the parameter was created updated_at: type: string description: When the parameter was last updated restart: type: boolean description: True if processes require a server restart on change max: type: number description: The maximum value of the parameter min: type: number description: The minimum value of the parameter step: type: number description: The step change of the parameter url: type: string description: The URL of the parameter options: items: type: string type: array description: Valid options for the parameter value actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url additionalProperties: false required: - id - name - display_name - namespace - category - description - extension - internal - parameter_type - default_value - value - required - created_at - updated_at - restart - max - min - step - url - options - actor additionalProperties: false required: - id - name - description - internal - url - parameters "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `read_branches` | | Database | `read_branches` | | Branch | `read_branch` | /organizations/{organization}/databases/{database}/branches/{branch}/keyspaces: get: tags: - Database branch keyspaces operationId: list_keyspaces summary: Get keyspaces parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: branch in: path required: true description: The name of the branch schema: type: string - name: page in: query description: If provided, specifies the page offset of returned results schema: type: number default: 1 - name: per_page in: query description: If provided, specifies the number of returned results schema: type: number default: 25 responses: "200": description: Returns keyspaces headers: {} content: application/json: schema: &a27 type: object properties: current_page: type: number description: The current page number next_page: type: number description: The next page number next_page_url: type: string description: The next page of results prev_page: type: number description: The previous page number prev_page_url: type: string description: The previous page of results data: type: array items: type: object properties: id: type: string description: The ID of the keyspace name: type: string description: Name of the keyspace shards: type: number description: The number of keyspace shards sharded: type: boolean description: If the keyspace is sharded replicas: type: number description: Total number of replicas in the keyspace extra_replicas: type: number description: Number of extra replicas in the keyspace created_at: type: string description: When the keyspace was created updated_at: type: string description: When the keyspace was last updated cluster_name: type: string description: The SKU representing the keyspace cluster size cluster_display_name: type: string description: The SKU representing the keyspace cluster size for display resizing: type: boolean description: Is the keyspace currently resizing resize_pending: type: boolean description: Is the keyspace awaiting a resize ready: type: boolean description: Is the keyspace provisioned and serving traffic metal: type: boolean description: Is the keyspace running on metal instances default: type: boolean description: Is this the default keyspace for the branch imported: type: boolean description: Is this keyspace used in an import vector_pool_allocation: type: number description: Percentage of buffer pool memory allocated to vector indexes replication_durability_constraints: type: object properties: strategy: type: string enum: - available - lag - always description: The replication durability strategy additionalProperties: false required: - strategy vreplication_flags: type: object properties: optimize_inserts: type: boolean description: Enable optimized inserts allow_no_blob_binlog_row_image: type: boolean description: Allow no blob binlog row image vplayer_batching: type: boolean description: Enable VPlayer batching additionalProperties: false required: - optimize_inserts - allow_no_blob_binlog_row_image - vplayer_batching additionalProperties: false required: - id - name - shards - sharded - replicas - extra_replicas - created_at - updated_at - cluster_name - cluster_display_name - resizing - resize_pending - ready - metal - default - imported - vector_pool_allocation - replication_durability_constraints - vreplication_flags additionalProperties: false required: - current_page - next_page - next_page_url - prev_page - prev_page_url - data "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |+ post: tags: - Database branch keyspaces operationId: create_keyspace summary: Create a keyspace parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: branch in: path required: true description: The name of the branch schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: The name of the keyspace additionalProperties: false required: - name responses: "200": description: Returns a created keyspace headers: {} content: application/json: schema: &a7 type: object properties: id: type: string description: The ID of the keyspace name: type: string description: Name of the keyspace shards: type: number description: The number of keyspace shards sharded: type: boolean description: If the keyspace is sharded replicas: type: number description: Total number of replicas in the keyspace extra_replicas: type: number description: Number of extra replicas in the keyspace created_at: type: string description: When the keyspace was created updated_at: type: string description: When the keyspace was last updated cluster_name: type: string description: The SKU representing the keyspace cluster size cluster_display_name: type: string description: The SKU representing the keyspace cluster size for display resizing: type: boolean description: Is the keyspace currently resizing resize_pending: type: boolean description: Is the keyspace awaiting a resize ready: type: boolean description: Is the keyspace provisioned and serving traffic metal: type: boolean description: Is the keyspace running on metal instances default: type: boolean description: Is this the default keyspace for the branch imported: type: boolean description: Is this keyspace used in an import vector_pool_allocation: type: number description: Percentage of buffer pool memory allocated to vector indexes replication_durability_constraints: type: object properties: strategy: type: string enum: - available - lag - always description: The replication durability strategy additionalProperties: false required: - strategy vreplication_flags: type: object properties: optimize_inserts: type: boolean description: Enable optimized inserts allow_no_blob_binlog_row_image: type: boolean description: Allow no blob binlog row image vplayer_batching: type: boolean description: Enable VPlayer batching additionalProperties: false required: - optimize_inserts - allow_no_blob_binlog_row_image - vplayer_batching additionalProperties: false required: - id - name - shards - sharded - replicas - extra_replicas - created_at - updated_at - cluster_name - cluster_display_name - resizing - resize_pending - ready - metal - default - imported - vector_pool_allocation - replication_durability_constraints - vreplication_flags "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |+ /organizations/{organization}/databases/{database}/branches/{branch}/keyspaces/{keyspace}/vschema: get: tags: - Keyspace VSchemas operationId: get_keyspace_vschema summary: Get the VSchema for the keyspace parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: branch in: path required: true description: The name of the branch schema: type: string - name: keyspace in: path required: true description: The name of the keyspace schema: type: string responses: "200": description: Returns the VSchema for the keyspace headers: {} content: application/json: schema: type: object properties: raw: type: string description: The keyspace's VSchema additionalProperties: false required: - raw "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |+ ### Authorization A service token must have at least one of the following access in order to use this API endpoint: **Service Token Accesses** `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` patch: tags: - Keyspace VSchemas operationId: update_keyspace_vschema summary: Update the VSchema for the keyspace parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: branch in: path required: true description: The name of the branch schema: type: string - name: keyspace in: path required: true description: The name of the keyspace schema: type: string requestBody: content: application/json: schema: type: object properties: vschema: type: string description: The new VSchema for the keyspace additionalProperties: false required: - vschema responses: "200": description: Returns the VSchema for the keyspace headers: {} content: application/json: schema: type: object properties: raw: type: string description: The keyspace's VSchema additionalProperties: false required: - raw "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "422": description: Unprocessable Content "500": description: Internal Server Error description: |+ ### Authorization A service token must have at least one of the following access in order to use this API endpoint: **Service Token Accesses** `write_production_branch_vschema`, `write_branch_vschema` /organizations/{organization}/databases/{database}/branches/{branch}/keyspaces/{name}: get: tags: - Database branch keyspaces operationId: get_keyspace summary: Get a keyspace parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: branch in: path required: true description: The name of the branch schema: type: string - name: name in: path required: true description: The name of the keyspace schema: type: string responses: "200": description: Returns information about a keyspace headers: {} content: application/json: schema: *a7 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |+ patch: tags: - Database branch keyspaces operationId: update_keyspace summary: Configure keyspace settings parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: branch in: path required: true description: The name of the branch schema: type: string - name: name in: path required: true description: The name of the keyspace schema: type: string responses: "200": description: Returns the keyspace headers: {} content: application/json: schema: *a7 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |+ delete: tags: - Database branch keyspaces operationId: delete_keyspace summary: Delete a keyspace parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: branch in: path required: true description: The name of the branch schema: type: string - name: name in: path required: true description: The name of the keyspace schema: type: string responses: "204": description: Delete a keyspace headers: {} "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |+ /organizations/{organization}/databases/{database}/branches/{branch}/keyspaces/{name}/rollout-status: get: tags: - Database branch keyspaces operationId: get_keyspace_rollout_status summary: Get keyspace rollout status parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: branch in: path required: true description: The name of the branch schema: type: string - name: name in: path required: true description: The name of the keyspace schema: type: string responses: "200": description: Returns information about a keyspace's rollout headers: {} content: application/json: schema: type: object properties: name: type: string description: The name of the keyspace state: type: string description: The current state of the rollout at the keyspace level shards: type: array items: type: object properties: name: type: string description: The name of the shard last_rollout_started_at: type: string description: The time at which the rollout started last_rollout_finished_at: type: string description: The time at which the rollout completed state: type: string description: The current state of the rollout at the shard level additionalProperties: false required: - name - last_rollout_started_at - last_rollout_finished_at - state additionalProperties: false required: - name - state - shards "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |+ /organizations/{organization}/databases/{database}/branches/{branch}/parameters: get: tags: - Cluster parameters operationId: list_parameters summary: List cluster parameters parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string responses: "200": description: Returns cluster parameters headers: {} content: application/json: schema: type: array items: &a26 type: object properties: id: type: string description: The ID of the parameter name: type: string description: The name of the parameter display_name: type: string description: The display name of the parameter namespace: type: string enum: - patroni - pgconf - pgbouncer description: The namespace of the parameter category: type: string description: The category of the parameter description: type: string description: The description of the parameter extension: type: boolean description: Configures an extension internal: type: boolean description: The internal state of the parameter parameter_type: type: string enum: - array - boolean - bytes - float - integer - internal - milliseconds - seconds - select - string - time description: The type of the parameter default_value: type: string description: The default value of the parameter value: type: string description: The configured value of the parameter required: type: boolean description: Whether the parameter is required created_at: type: string description: When the parameter was created updated_at: type: string description: When the parameter was last updated restart: type: boolean description: True if processes require a server restart on change max: type: number description: The maximum value of the parameter min: type: number description: The minimum value of the parameter step: type: number description: The step change of the parameter url: type: string description: The URL of the parameter options: items: type: string type: array description: Valid options for the parameter value actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url additionalProperties: false required: - id - name - display_name - namespace - category - description - extension - internal - parameter_type - default_value - value - required - created_at - updated_at - restart - max - min - step - url - options - actor "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |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: number default: 1 - name: per_page in: query description: If provided, specifies the number of returned results schema: type: number default: 25 responses: "200": description: Returns passwords for the branch headers: {} content: application/json: schema: &a28 type: object properties: current_page: type: number description: The current page number next_page: type: number description: The next page number next_page_url: type: string description: The next page of results prev_page: type: number description: The previous page number prev_page_url: type: string description: The previous page of results data: type: array items: type: object properties: id: type: string description: The ID for the password name: type: string description: The display name for the password role: type: string enum: - reader - writer - admin - readwriter description: The role for the password cidrs: items: type: string type: array description: List of IP addresses or CIDR ranges that can use this password created_at: type: string description: When the password was created deleted_at: type: string description: When the password was deleted expires_at: type: string description: When the password will expire last_used_at: type: string description: When the password was last used to execute a query expired: type: boolean description: True if the credentials are expired direct_vtgate: type: boolean description: True if the credentials connect directly to a vtgate, bypassing load balancers ttl_seconds: type: number description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed access_host_url: type: string description: The host URL for the password access_host_regional_url: type: string description: The regional host URL access_host_regional_urls: items: type: string type: array description: The read-only replica host URLs actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url region: type: object properties: id: type: string description: The ID of the region provider: type: string description: Provider for the region (ex. AWS) enabled: type: boolean description: Whether or not the region is currently active public_ip_addresses: items: type: string type: array description: Public IP addresses for the region display_name: type: string description: Name of the region location: type: string description: Location of the region slug: type: string description: The slug of the region current_default: type: boolean description: True if the region is the default for new branch creation additionalProperties: false required: - id - provider - enabled - public_ip_addresses - display_name - location - slug - current_default username: type: string description: The username for the password plain_text: type: string description: The plain text password, available only after create replica: type: boolean description: Whether or not the password is for a read replica renewable: type: boolean description: Whether or not the password can be renewed database_branch: type: object properties: name: type: string description: The name for the branch id: type: string description: The ID for the branch production: type: boolean description: Whether or not the branch is a production branch mysql_edge_address: type: string description: The address of the MySQL provider for the branch private_edge_connectivity: type: boolean description: True if private connectivity is enabled additionalProperties: false required: - name - id - production - mysql_edge_address - private_edge_connectivity additionalProperties: false required: - id - name - role - cidrs - created_at - deleted_at - expires_at - last_used_at - expired - direct_vtgate - ttl_seconds - access_host_url - access_host_regional_url - access_host_regional_urls - actor - region - username - plain_text - replica - renewable - database_branch additionalProperties: false required: - current_page - next_page - next_page_url - prev_page - prev_page_url - data "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `manage_passwords`, `manage_production_branch_passwords` | | Database | `manage_passwords`, `manage_production_branch_passwords` | | Branch | `manage_passwords` | post: tags: - Database branch passwords operationId: create_password summary: Create a password parameters: - name: organization in: path required: true description: The name of the organization the password belongs to schema: type: string - name: database in: path required: true description: The name of the database the password belongs to schema: type: string - name: branch in: path required: true description: The name of the branch the password belongs to schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: Optional name of the password role: type: string enum: - reader - writer - admin - readwriter description: The database role of the password (i.e. admin) replica: type: boolean description: Whether the password is for a read replica ttl: type: number description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed cidrs: type: array items: type: string description: List of IP addresses or CIDR ranges that can use this password direct_vtgate: type: boolean description: Whether the password connects directly to a VTGate additionalProperties: false responses: "201": description: Returns the new credentials headers: {} content: application/json: schema: &a8 type: object properties: id: type: string description: The ID for the password name: type: string description: The display name for the password role: type: string enum: - reader - writer - admin - readwriter description: The role for the password cidrs: items: type: string type: array description: List of IP addresses or CIDR ranges that can use this password created_at: type: string description: When the password was created deleted_at: type: string description: When the password was deleted expires_at: type: string description: When the password will expire last_used_at: type: string description: When the password was last used to execute a query expired: type: boolean description: True if the credentials are expired direct_vtgate: type: boolean description: True if the credentials connect directly to a vtgate, bypassing load balancers ttl_seconds: type: number description: Time to live (in seconds) for the password. The password will be invalid when TTL has passed access_host_url: type: string description: The host URL for the password access_host_regional_url: type: string description: The regional host URL access_host_regional_urls: items: type: string type: array description: The read-only replica host URLs actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url region: type: object properties: id: type: string description: The ID of the region provider: type: string description: Provider for the region (ex. AWS) enabled: type: boolean description: Whether or not the region is currently active public_ip_addresses: items: type: string type: array description: Public IP addresses for the region display_name: type: string description: Name of the region location: type: string description: Location of the region slug: type: string description: The slug of the region current_default: type: boolean description: True if the region is the default for new branch creation additionalProperties: false required: - id - provider - enabled - public_ip_addresses - display_name - location - slug - current_default username: type: string description: The username for the password plain_text: type: string description: The plain text password, available only after create replica: type: boolean description: Whether or not the password is for a read replica renewable: type: boolean description: Whether or not the password can be renewed database_branch: type: object properties: name: type: string description: The name for the branch id: type: string description: The ID for the branch production: type: boolean description: Whether or not the branch is a production branch mysql_edge_address: type: string description: The address of the MySQL provider for the branch private_edge_connectivity: type: boolean description: True if private connectivity is enabled additionalProperties: false required: - name - id - production - mysql_edge_address - private_edge_connectivity additionalProperties: false required: - id - name - role - cidrs - created_at - deleted_at - expires_at - last_used_at - expired - direct_vtgate - ttl_seconds - access_host_url - access_host_regional_url - access_host_regional_urls - actor - region - username - plain_text - replica - renewable - database_branch "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "422": description: Unprocessable Content "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `connect_production_branch`, `connect_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `manage_passwords`, `manage_production_branch_passwords` | | Database | `manage_passwords`, `manage_production_branch_passwords` | | Branch | `manage_passwords` | /organizations/{organization}/databases/{database}/branches/{branch}/passwords/{id}: get: tags: - Database branch passwords operationId: get_password summary: Get a password parameters: - name: organization in: path required: true description: The name of the organization the password belongs to schema: type: string - name: database in: path required: true description: The name of the database the password belongs to schema: type: string - name: branch in: path required: true description: The name of the branch the password belongs to schema: type: string - name: id in: path required: true description: The ID of the password schema: type: string responses: "200": description: Returns a password headers: {} content: application/json: schema: *a8 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `manage_passwords`, `manage_production_branch_passwords` | | Database | `manage_passwords`, `manage_production_branch_passwords` | | Branch | `manage_passwords` | patch: tags: - 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: *a8 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `connect_production_branch`, `connect_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `manage_passwords`, `manage_production_branch_passwords` | | Database | `manage_passwords`, `manage_production_branch_passwords` | | Branch | `manage_passwords` | delete: tags: - Database branch passwords operationId: delete_password summary: Delete a password parameters: - name: organization in: path required: true description: The name of the organization the password belongs to schema: type: string - name: database in: path required: true description: The name of the database the password belongs to schema: type: string - name: branch in: path required: true description: The name of the branch the password belongs to schema: type: string - name: id in: path required: true description: The ID of the password schema: type: string responses: "204": description: Deletes the password headers: {} "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `delete_production_branch_password`, `delete_branch_password` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `manage_passwords`, `manage_production_branch_passwords` | | Database | `manage_passwords`, `manage_production_branch_passwords` | | Branch | `manage_passwords` | /organizations/{organization}/databases/{database}/branches/{branch}/passwords/{id}/renew: post: tags: - Database branch passwords operationId: renew_password summary: Renew a password parameters: - name: organization in: path required: true description: The name of the organization the password belongs to schema: type: string - name: database in: path required: true description: The name of the database the password belongs to schema: type: string - name: branch in: path required: true description: The name of the branch the password belongs to schema: type: string - name: id in: path required: true description: The ID of the password schema: type: string responses: "200": description: Returns the renewed password headers: {} content: application/json: schema: *a8 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `connect_production_branch`, `connect_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `manage_passwords`, `manage_production_branch_passwords` | | Database | `manage_passwords`, `manage_production_branch_passwords` | | Branch | `manage_passwords` | /organizations/{organization}/databases/{database}/branches/{branch}/query-patterns: get: tags: - Query Insights reports operationId: list_generated_query_patterns_reports summary: List generated query patterns reports parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: branch in: path required: true description: The name of the branch schema: type: string responses: "200": description: Returns the generated query patterns reports headers: {} content: application/json: schema: &a42 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: &a9 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: *a9 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_branch` **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: *a9 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `read_branches` | | Database | `read_branches` | | Branch | `read_branch` | /organizations/{organization}/databases/{database}/branches/{branch}/resizes: delete: tags: - Branch changes operationId: cancel_branch_change_request summary: Cancel a change request parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string responses: "204": description: Cancels a change request headers: {} "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `write_database` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_databases` | | Database | `write_database` | /organizations/{organization}/databases/{database}/branches/{branch}/roles: get: tags: - Roles operationId: list_roles summary: List roles parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string - name: page in: query description: If provided, specifies the page offset of returned results schema: type: number default: 1 - name: per_page in: query description: If provided, specifies the number of returned results schema: type: number default: 25 responses: "200": description: Returns roles headers: {} content: application/json: schema: &a41 type: object properties: current_page: type: number description: The current page number next_page: type: number description: The next page number next_page_url: type: string description: The next page of results prev_page: type: number description: The previous page number prev_page_url: type: string description: The previous page of results data: type: array items: type: object properties: id: type: string description: The ID of the role name: type: string description: The name of the role access_host_url: type: string description: The database connection string private_access_host_url: type: string description: The database connection string for private connections private_connection_service_name: type: string description: The service name to set up private connectivity username: type: string description: The database user name password: type: string description: The plain text password, available only after create database_name: type: string description: The database name created_at: type: string description: When the role was created updated_at: type: string description: When the role was updated deleted_at: type: string description: When the role was deleted expires_at: type: string description: When the role expires dropped_at: type: string description: When the role was dropped drop_failed: type: string description: Error message available when dropping the role fails expired: type: boolean description: True if the credentials are expired default: type: boolean description: Whether the role is the default postgres user ttl: type: number description: Number of seconds before the credentials expire inherited_roles: items: type: string enum: - pg_checkpoint - pg_create_subscription - pg_maintain - pg_monitor - pg_read_all_data - pg_read_all_settings - pg_read_all_stats - pg_signal_backend - pg_stat_scan_tables - pg_use_reserved_connections - pg_write_all_data - postgres type: array description: Database roles these credentials inherit branch: type: object properties: id: type: string description: The ID for the resource name: type: string description: The name for the resource created_at: type: string description: When the resource was created updated_at: type: string description: When the resource was last updated deleted_at: type: string description: When the resource was deleted, if deleted additionalProperties: false required: - id - name - created_at - updated_at - deleted_at actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url additionalProperties: false required: - id - name - access_host_url - private_access_host_url - private_connection_service_name - username - password - database_name - created_at - updated_at - deleted_at - expires_at - dropped_at - drop_failed - expired - default - ttl - inherited_roles - branch - actor additionalProperties: false required: - current_page - next_page - next_page_url - prev_page - prev_page_url - data "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `manage_passwords`, `manage_production_branch_passwords` | | Database | `manage_passwords`, `manage_production_branch_passwords` | | Branch | `manage_passwords` | post: tags: - Roles operationId: create_role summary: Create role credentials parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string requestBody: content: application/json: schema: type: object properties: ttl: type: number description: Time to live in seconds inherited_roles: type: array items: type: string enum: - pg_checkpoint - pg_create_subscription - pg_maintain - pg_monitor - pg_read_all_data - pg_read_all_settings - pg_read_all_stats - pg_signal_backend - pg_stat_scan_tables - pg_use_reserved_connections - pg_write_all_data - postgres description: Roles to inherit from additionalProperties: false responses: "200": description: Returns the new credentials headers: {} content: application/json: schema: &a10 type: object properties: id: type: string description: The ID of the role name: type: string description: The name of the role access_host_url: type: string description: The database connection string private_access_host_url: type: string description: The database connection string for private connections private_connection_service_name: type: string description: The service name to set up private connectivity username: type: string description: The database user name password: type: string description: The plain text password, available only after create database_name: type: string description: The database name created_at: type: string description: When the role was created updated_at: type: string description: When the role was updated deleted_at: type: string description: When the role was deleted expires_at: type: string description: When the role expires dropped_at: type: string description: When the role was dropped drop_failed: type: string description: Error message available when dropping the role fails expired: type: boolean description: True if the credentials are expired default: type: boolean description: Whether the role is the default postgres user ttl: type: number description: Number of seconds before the credentials expire inherited_roles: items: type: string enum: - pg_checkpoint - pg_create_subscription - pg_maintain - pg_monitor - pg_read_all_data - pg_read_all_settings - pg_read_all_stats - pg_signal_backend - pg_stat_scan_tables - pg_use_reserved_connections - pg_write_all_data - postgres type: array description: Database roles these credentials inherit branch: type: object properties: id: type: string description: The ID for the resource name: type: string description: The name for the resource created_at: type: string description: When the resource was created updated_at: type: string description: When the resource was last updated deleted_at: type: string description: When the resource was deleted, if deleted additionalProperties: false required: - id - name - created_at - updated_at - deleted_at actor: type: object properties: id: type: string description: The ID of the actor display_name: type: string description: The name of the actor avatar_url: type: string description: The URL of the actor's avatar additionalProperties: false required: - id - display_name - avatar_url additionalProperties: false required: - id - name - access_host_url - private_access_host_url - private_connection_service_name - username - password - database_name - created_at - updated_at - deleted_at - expires_at - dropped_at - drop_failed - expired - default - ttl - inherited_roles - branch - actor "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `create_production_branch_password`, `create_branch_password` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `manage_passwords`, `manage_production_branch_passwords` | | Database | `manage_passwords`, `manage_production_branch_passwords` | | Branch | `manage_passwords` | /organizations/{organization}/databases/{database}/branches/{branch}/roles/{id}: get: tags: - Roles operationId: get_role summary: Get a role parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string - name: id in: path required: true description: The ID of the role schema: type: string responses: "200": description: Returns a role headers: {} content: application/json: schema: *a10 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `manage_passwords`, `manage_production_branch_passwords` | | Database | `manage_passwords`, `manage_production_branch_passwords` | | Branch | `manage_passwords` | patch: tags: - Roles operationId: update_role summary: Update role name parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string - name: id in: path required: true description: The ID of the role schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: The new name of the role additionalProperties: false responses: "200": description: Returns the updated role headers: {} content: application/json: schema: *a10 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `create_production_branch_password`, `create_branch_password` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `manage_passwords`, `manage_production_branch_passwords` | | Database | `manage_passwords`, `manage_production_branch_passwords` | | Branch | `manage_passwords` | delete: tags: - Roles operationId: delete_role summary: Delete role credentials parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string - name: id in: path required: true description: The ID of the role schema: type: string requestBody: content: application/json: schema: type: object properties: successor: type: string description: The optional role to reassign ownership to before dropping additionalProperties: false responses: "204": description: Deletes the role credentials headers: {} "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `delete_production_branch_password`, `delete_branch_password` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `manage_passwords`, `manage_production_branch_passwords` | | Database | `manage_passwords`, `manage_production_branch_passwords` | | Branch | `manage_passwords` | /organizations/{organization}/databases/{database}/branches/{branch}/roles/{id}/renew: post: tags: - Roles operationId: renew_role summary: Renew role expiration parameters: - name: organization in: path required: true description: The name of the organization that owns this resource schema: type: string - name: database in: path required: true description: The name of the database that owns this resource schema: type: string - name: branch in: path required: true description: The name of the branch that owns this resource schema: type: string - name: id in: path required: true description: The ID of the role schema: type: string responses: "200": description: Returns the renewed role headers: {} content: application/json: schema: *a10 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `create_production_branch_password`, `create_branch_password` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `manage_passwords`, `manage_production_branch_passwords` | | Database | `manage_passwords`, `manage_production_branch_passwords` | | Branch | `manage_passwords` | /organizations/{organization}/databases/{database}/branches/{name}: get: tags: - Database branches operationId: get_branch summary: Get a branch parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: name in: path required: true description: The name of the branch schema: type: string responses: "200": description: Returns information about a branch headers: {} content: application/json: schema: *a11 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `read_branch`, `delete_branch`, `create_branch`, `connect_production_branch`, `connect_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `read_branches` | | Database | `read_branches` | | Branch | `read_branch` | delete: tags: - Database branches operationId: delete_branch summary: Delete a branch parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: name in: path required: true description: The name of the branch schema: type: string responses: "204": description: Delete a branch headers: {} "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `delete_branch` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `delete_branches`, `delete_production_branches` | | Database | `delete_branches`, `delete_production_branches` | | Branch | `delete_branch` | /organizations/{organization}/databases/{database}/branches/{name}/cluster: patch: tags: - Database branches operationId: update_branch_cluster_config summary: Change a branch cluster configuration parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: name in: path required: true description: The name of the branch to configure schema: type: string requestBody: content: application/json: schema: type: object properties: cluster_size: type: string description: "The new size of the database cluster: PS_10, PS_20,…" additionalProperties: false required: - cluster_size responses: "204": description: Returns an empty response body headers: {} "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |+ ### Authorization A service token must have at least one of the following access in order to use this API endpoint: **Service Token Accesses** `write_database` /organizations/{organization}/databases/{database}/branches/{name}/demote: post: tags: - Database branches operationId: demote_branch summary: Demote a branch parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: name in: path required: true description: The name of the branch schema: type: string responses: "200": description: Returns a development branch headers: {} content: application/json: schema: *a11 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- Demotes a branch from production to development ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `connect_production_branch`, `demote_branches` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `demote_branches` | | Database | `demote_branches` | /organizations/{organization}/databases/{database}/branches/{name}/promote: post: tags: - Database branches operationId: promote_branch summary: Promote a branch parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: name in: path required: true description: The name of the branch schema: type: string responses: "200": description: Returns a production branch headers: {} content: application/json: schema: *a11 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |- Promotes a branch from development to production ### Authorization A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint: **Service Token Accesses** `connect_production_branch`, `promote_branches` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `promote_branches` | | Database | `promote_branches` | /organizations/{organization}/databases/{database}/branches/{name}/safe-migrations: post: tags: - Database branches operationId: enable_safe_migrations summary: Enable safe migrations for a branch parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: name in: path required: true description: The name of the branch schema: type: string responses: "200": description: Returns the branch with safe migrations enabled headers: {} content: application/json: schema: *a11 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |+ delete: tags: - Database branches operationId: disable_safe_migrations summary: Disable safe migrations for a branch parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: name in: path required: true description: The name of the branch schema: type: string responses: "200": description: Returns the branch with safe migrations disabled headers: {} content: application/json: schema: *a11 "401": description: Unauthorized "403": description: Forbidden "404": description: Not Found "500": description: Internal Server Error description: |+ /organizations/{organization}/databases/{database}/branches/{name}/schema: get: tags: - Database branches operationId: get_branch_schema summary: Get a branch schema parameters: - name: organization in: path required: true description: The name of the organization the branch belongs to schema: type: string - name: database in: path required: true description: The name of the database the branch belongs to schema: type: string - name: name in: path required: true description: The name of the branch schema: type: string - name: keyspace in: query description: Return the schema for a single Vitess keyspace schema: type: string - name: namespace in: query description: Return the schema for a PostgreSQL catalog namespace in `