openapi: 3.0.1
info:
  contact:
    email: support@aiven.io
    name: Aiven support team
    url: https://aiven.io/support-services
  title: Aiven API Documentation Account Service:_PostgreSQL API
  version: v1
  x-logo:
    altText: Aiven logo
    backgroundColor: '#fafafa'
    href: https://api.aiven.io/doc
    url: https://aiven.io/assets/img/aiven-logo.png
  description: "# Introduction\n\n[Direct link to openapi.json](https://api.aiven.io/doc/openapi.json) for use with external tools\n\n[Aiven](https://aiven.io) is a modern fully-managed open source data platform for streaming, storing, and analyzing data on any public cloud. On Aiven Platform, you can operate your data infrastructure with a few devops tools: [Aiven Console](https://console.aiven.io/), [Aiven Terraform Provider](https://aiven.io/docs/tools/terraform), [Aiven CLI](https://github.com/aiven/aiven-client), and [Aiven Operator for Kubernetes](https://github.com/aiven/aiven-operator). All of them are built on an open secure powerful REST API for integration with custom tooling.\n\nThe Aiven [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) API\nprovides programmatic access to Aiven.io services. To call the Aiven API, you can use either CLI tools (for example, `cURL` or [Aiven CLI client](https://aiven.io/docs/tools/cli)) or GUI tools, such as the [Aiven public API Postman collection](https://www.postman.com/aiven-apis).\n\nThis Aiven API documentation will help you operate your Aiven organization, projects, or services programmatically by integrating your applications and processes with Aiven.\n\n# Description\n\nAiven's APIs ([Application Programming Interfaces](https://en.wikipedia.org/wiki/API)) power its platform for data management. Aiven has a number of REST APIs that can help you build strong and robust data infrastructure for your applications.\n\nThe Aiven API is organized around core resources. Each core resource has multiple endpoints, which can be interacted with using different HTTP methods.\n\n## Core resources\n\n### Platform APIs\n\n<dl>\n  <dt>Account</dt>\n  <dd>Operations on the organization level related to accounts, projects, teams, users, invites, billing groups, payment methods, credit cards, authentication methods, and more </dd>\n  <dt>User</dt>\n  <dd>Operations related to users and users' profiles, access, authentication, authorization, user management, and more</dd>\n  <dt>Project</dt>\n  <dd>General operations on projects related to users, VPCs, invitations, alerts, peering connections, and more</dd>\n  <dt>BillingGroup</dt>\n  <dd>Operation on invoices, billing groups' credits and events </dd>\n  <dt>Support ticket</dt>\n  <dd>Operations on support tickets: listing, creating, looping users in</dd>\n</dl>\n\n### Services APIs\n\n<dl>\n  <dt>Service</dt>\n  <dd>All general (non-service-specific) operations on the service level: service creation, termination, configuration, updates, information retrieval, reset, and more</dd>\n  <dt>Service Integrations</dt>\n  <dd>Operations related to integrating services and managing service integrations</dd>\n  <dt>Service: ClickHouse</dt>\n  <dd>ClickHouse-specific operations on queries and databases </dd>\n  <dt>Service: Flink</dt>\n  <dd>Operations on Flink queries, jobs, and applications</dd>\n  <dt>Service: Kafka</dt>\n  <dd>Kafka and Kafka Connect specific operations on connectors, ACL entries, quotas, topics, topic messages, schema registry, and more</dd>\n  <dt>Service: Kafka MirrorMaker</dt>\n  <dd>Operations on replication flows</dd>\n  <dt>Service: MySQL</dt>\n  <dd>Fetching service query statistics</dd>\n  <dt>Service: OpenSearch</dt>\n  <dd>Operations on ACL configuration, security administration and configuration</dd>\n  <dt>Service: PostgreSQL</dt>\n  <dd>Operations on extensions, service query statistics, and connection pools</dd>\n</dl>\n\n# Requests\n\nThere are multiple ways you can interact with the Aiven API over HTTP. You can access it by sending requests from a client (for example, a web browser) to the Aiven's server. In this API reference, you'll find code examples of how to do that using `cURL` and a few different client libraries (programming languages).\n\nTo send an API request, you need to specify the following:\n\n* HTTP method\n* Path\n* Request headers\n\n  Typically, `content-type` needs to be set to `application/json`: `content-type: application/json`. There are a few exceptions though.\n\n* Path, query, or body parameters (either required or optional).\n\n```bash\ncurl --request POST \\\n  --url https://api.aiven.io/v1/project/{project}/vpcs \\\n  --header 'Authorization: aivenv1 REPLACE_BEARER_TOKEN' \\\n  --header 'content-type: application/json' \\\n  --data\n     '{\n        \"cloud_name\": \"string\",\n        \"network_cidr\": \"string\",\n        \"peering_connections\": [\n          {\n            \"peer_azure_app_id\": \"string\",\n            \"peer_azure_tenant_id\": \"string\",\n            \"peer_cloud_account\": \"string\",\n            \"peer_region\": \"string\",\n            \"peer_resource_group\": \"string\",\n            \"peer_vpc\": \"string\",\n            \"user_peer_network_cidrs\": [\n              \"string\"\n            ]\n          }\n        ]\n      }'\n```\n\n# Responses\n\nUpon receiving and processing a request, the Aiven API returns the response status code, response headers, and a response body in the `JSON` format. Response bodies include different properties, which can be either required or optional, for example, the ``message`` property, which is an optional human-readable information on the result of the action (deleted, created, or updated).\n\n```json\n{\n    \"cloud_name\": \"string\",\n    \"create_time\": \"string\",\n    \"message\": \"string\",\n    \"network_cidr\": \"string\",\n    \"peering_connections\": [\n        { ... }\n    ],\n    \"pending_build_only_peering_connections\": \"string\",\n    \"project_vpc_id\": \"string\",\n    \"state\": \"ACTIVE\",\n    \"update_time\": \"string\"\n}\n```\n\n## Successful responses\n\nA successful API response returns an HTTP result code between 200 and 299.\n\nExample of the ``created`` response\n\n```json\n  {\n      \"service\": {\n          \"service_name\": \"foobar\",\n          ...\n      }\n  }\n```\n\n## Failed responses\n\nA failed API response returns a HTTP code greater or equal to 400. Additionally, the response may return a list of errors in the response body as JSON, for example\n\n```json\n{\n  \"errors\": [\n    {\n      \"error_code\": \"authentication_failed\",\n      \"message\": \"Authentication failed\",\n      \"status\": 403,\n      \"metadata\": {\n        ...\n      }\n    }\n  ],\n  \"message\": \"Authentication failed\"\n}\n```\n\n> For information on errors' properties and error codes, check [Errors](/doc/openapi/openapi-description#errors).\n\n# Get started\n\nCheck out how to start using the Aiven API either in [API quick start](https://aiven.io/docs/tools/api#api-quickstart) or [Your first API call](https://aiven.io/blog/your-first-aiven-api-call).\n\n## Authentication\n\n<!-- ReDoc-Inject: <security-definitions> -->\n\n# Errors\n\nWhen working with the Aiven API, you may encounter different error responses when you attempt to perform operations that can fail. For example, trying to enable writes for a database that has been powered off would lead to the following error response:\n\n```json\n{\n  \"errors\": [\n    {\n      \"error_code\": \"not_powered\",\n      \"message\": \"Database not powered on\",\n      \"status\": 409\n    }\n  ],\n  \"message\": \"Database not powered on\"\n}\n```\n\n## Check a response for errors\n\nIf a request fails with a HTTP code greater or equal to 400, it returns a list of errors in the response body as JSON. `errors` objects are embedded in the failed API responses.\n\n```json\n{\n  \"errors\": [\n    {\n      \"error_code\": \"account_not_found\",\n      \"message\": \"Account does not exist\",\n      \"status\": 404\n    }\n  ],\n  \"message\": \"Account does not exist\"\n}\n```\n\n## Errors' properties\n\nIn an API response, one or more errors may be included in the ``errors`` array of objects. Each error object may contain a few properties:\n\n* ``status`` (required) is an HTTP error code, which can be used to programmatically identify the error type.\n\n  * ``200`` <= ``status``< ``300`` means a successful request.\n  * ``300`` <= ``status`` <= ``500`` means a failed request.\n\n  ``errors`` can have the following HTTPS status codes:\n\n  * 200 - OK\n  * 201 - Created\n  * 400 - Bad Request\n  * 401 - Unauthorized\n  * 403 - Forbidden\n  * 404 - Not found\n  * 405 - Method Not Allowed\n  * 409 - Conflict\n  * 500 - Internal Server Error\n\n* ``message`` (required) is human-readable information on the error.\n* ``error_code`` is a machine-readable information on the error (see [Error codes](/doc/openapi/openapi-description#error-codes)).\n\n## Error codes\n\nMachine-readable ``error_code`` fields are progressively added to Aiven endpoints to allow you to identify different failure cases programmatically. Currently, the supported values are the following:\n\n- `account_already_exists`\n- `account_already_has_organization`\n- `account_and_project_do_not_match`\n- `account_and_project_must_belong_same_tenant`\n- `account_cannot_be_own_ancestor`\n- `account_must_have_enabled_authentication_method`\n- `account_not_found`\n- `account_team_not_found`\n- `account_unit_cannot_create_for_personal_tier`\n- `account_unit_cannot_have_billing_group`\n- `account_with_child_accounts_cannot_be_deleted`\n- `account_with_projects_cannot_be_deleted`\n- `action_forbidden_for_application_users`\n- `action_forbidden_for_managed_users`\n- `action_forbidden_for_marketplace_users`\n- `action_forbidden_for_scim_users`\n- `action_forbidden_for_timescale_users`\n- `action_forbidden_missing_governance_usergroup`\n- `action_forbidden_on_application_users`\n- `action_forbidden_on_topic_request`\n- `action_forbidden_on_unmanaged_users`\n- `acu_billing_not_allowed`\n- `address_already_belongs_to_organization`\n- `address_in_use`\n- `address_not_found`\n- `api_client_ip_allowlist_blocks_caller`\n- `approval_forbidden_on_topic_request`\n- `approval_missing_on_request`\n- `auth_token_max_age_too_low`\n- `authentication_method_disable_current_not_allowed`\n- `authentication_method_does_not_allow_auto_join_user_group`\n- `authentication_method_limit_reached`\n- `authentication_method_not_found`\n- `backup_failed`\n- `bad_request`\n- `billing_address_not_found`\n- `billing_customer_id_not_found`\n- `billing_group_not_found`\n- `billing_group_organization_active_trial`\n- `billing_group_owning_account_must_be_organization`\n- `billing_metronome_support_contract_not_found`\n- `ca_version_not_in_sequence`\n- `cannot_delete_active_managed_users`\n- `cannot_delete_users_with_organizations_memberships`\n- `cannot_move_project_not_assigned_to_organization`\n- `cannot_remove_managed_users_from_organization`\n- `cannot_set_groups_managed_by_scim_as_auto_join_group`\n- `client_ip_address_policy_violation`\n- `credit_card_not_found`\n- `credit_memo_not_found`\n- `custom_cloud_environment_cloud_not_supported`\n- `custom_cloud_environment_internal`\n- `custom_cloud_environment_invalid_iam_role_arn`\n- `custom_cloud_environment_missing_configuration`\n- `custom_cloud_environment_not_found`\n- `custom_cloud_environment_region_not_supported`\n- `database_not_found`\n- `decline_forbidden_on_topic_request`\n- `deleting_forbidden_on_governance_request`\n- `deleting_forbidden_on_topic_request`\n- `discount_not_found`\n- `feature_not_enabled`\n- `free_plans_in_high_demand_and_unavailable`\n- `free_tier_restricted`\n- `free_trial_extensions_not_available`\n- `free_trial_max_extended`\n- `free_trial_not_active`\n- `free_trial_not_available`\n- `governance_access_no_permission_on_project`\n- `governance_access_not_found`\n- `governance_configuration_already_exists`\n- `governance_configuration_not_found`\n- `governance_group_not_found`\n- `governance_invalid_service_type`\n- `governance_request_already_in_progress`\n- `governance_request_deleted`\n- `idp_no_domains_linked`\n- `index_close_failed`\n- `index_not_found`\n- `internal_server_error`\n- `invalid_backup_configuration`\n- `invalid_cmk_id`\n- `invalid_currency_code`\n- `invalid_date_format`\n- `invalid_email_format`\n- `invalid_governance_group_provided`\n- `invalid_kafka_topic_request_type`\n- `invalid_os_migration_command`\n- `invalid_owner_user_group`\n- `invalid_private_access_settings`\n- `invalid_scim_user_state_update`\n- `invalid_service_type`\n- `invalid_vcs_type`\n- `invitation_expired`\n- `invitation_not_found`\n- `invoice_lines_not_supported`\n- `invoice_not_found`\n- `ip_address_not_present`\n- `ip_address_not_valid`\n- `kafka_acl_not_supported`\n- `kafka_console_governance_enabled`\n- `kafka_governance_not_available`\n- `kafka_governance_not_enabled`\n- `kafka_governance_policy_incomplete`\n- `kafka_partition_reassignment_in_progress`\n- `kafka_policy_violation`\n- `kafka_service_unavailable`\n- `kafka_terraform_governance_enabled`\n- `kafka_topic_already_exists`\n- `kafka_topic_invalid_config`\n- `kafka_topic_not_found`\n- `kafka_topic_not_synchronized`\n- `kafka_topic_queued_for_deletion`\n- `kafka_topic_reserved`\n- `marketplace_aws_customer_or_product_details_not_found`\n- `marketplace_subscription_already_linked_to_organization`\n- `marketplace_subscription_link_expired`\n- `marketplace_subscription_no_access`\n- `metadata_validation_failed`\n- `mfa_required_by_organization`\n- `mp_account_with_active_subscription_deleted`\n- `mp_account_with_commitment_deleted`\n- `mp_account_with_support_contract_deleted`\n- `mp_subscription_not_found`\n- `nested_account_cannot_have_authentication_method`\n- `nested_account_cannot_have_user_groups`\n- `new_subnet_id_required`\n- `no_failed_os_migration`\n- `node_prune_version_not_updated`\n- `not_powered`\n- `opensearch_delete_system_index`\n- `opensearch_internal_server_error`\n- `opensearch_service_unavailable`\n- `opensearch_too_many_requests`\n- `optimization_failed`\n- `optimization_not_found`\n- `organization_aiven_enterprise_contract_denied`\n- `organization_aiven_enterprise_contract_feature_denied`\n- `organization_aiven_enterprise_denied`\n- `organization_aiven_enterprise_organization_required`\n- `organization_cannot_exist_without_root_account`\n- `organization_domain_already_linked`\n- `organization_domain_not_found`\n- `organization_domain_not_root`\n- `organization_domain_verification_failed`\n- `organization_has_active_addresses`\n- `organization_has_active_payment_methods`\n- `organization_kafka_topics_invalid_filters`\n- `organization_mismatch`\n- `organization_must_have_one_super_admin`\n- `organization_not_found`\n- `organization_pending_support_contract_already_exists`\n- `organization_support_contract_tier_not_supported`\n- `organization_tier_downgrade_not_allowed`\n- `organization_user_not_found`\n- `orphaned_project_not_allowed`\n- `parent_account_cannot_be_own_ancestor`\n- `parent_account_not_found`\n- `parent_account_tenant_invalid`\n- `parent_account_too_deep`\n- `payment_method_not_found`\n- `permission_denied`\n- `pg_editor_readonly_violation`\n- `pg_pool_already_exists`\n- `pg_pool_invalid_database`\n- `pg_pool_invalid_name`\n- `pg_pool_not_found`\n- `pg_pool_not_supported`\n- `pg_pool_pinned_pools_not_enabled`\n- `pg_pool_requires_pinned_pools`\n- `pg_pool_too_big`\n- `pg_pool_too_many`\n- `pg_publication_not_found`\n- `pg_replication_slot_not_found`\n- `pg_scram_not_allowed`\n- `project_account_not_active`\n- `project_already_exists`\n- `project_belongs_to_account_billing_group_must_use_api`\n- `project_does_not_exist`\n- `project_has_no_such_user`\n- `project_limitation_not_found`\n- `project_move_invalid`\n- `project_move_organizations_internal_config_not_match`\n- `project_not_found`\n- `project_without_billing_group_must_be_assigned_from_account`\n- `query_validation_failed`\n- `replication_already_exists`\n- `replication_config_invalid`\n- `replication_not_found`\n- `replication_service_not_found`\n- `repository_not_found`\n- `request_already_exists`\n- `request_forbidden`\n- `request_not_found`\n- `request_operation_already_exists`\n- `request_operation_not_found`\n- `resource_managed_by_governance`\n- `resource_managed_by_scim`\n- `resource_not_managed_by_scim`\n- `retired_api_endpoint`\n- `root_account_required`\n- `same_organization_required`\n- `schema_insights_failed`\n- `service_acl_not_found`\n- `service_acl_too_many`\n- `service_does_not_exist`\n- `service_governance_not_enabled`\n- `service_integration_endpoint_not_found`\n- `service_integration_not_found`\n- `service_integration_project_mismatch_source_destination`\n- `service_is_upgrade_pipeline_source`\n- `service_logs_backend_timeout`\n- `service_logs_backend_unavailable`\n- `service_maintenance_required`\n- `service_not_found`\n- `service_type_not_allowed`\n- `service_type_version_pin_locked`\n- `shipping_address_not_found`\n- `signup_welcome_invalid_key`\n- `snapshot_creation_failed`\n- `snapshot_deletion_failed`\n- `snapshot_not_found`\n- `snapshot_restoration_failed`\n- `stripe_customer_owning_account_must_be_organization`\n- `support_contract_and_account_must_be_in_same_organization`\n- `support_contract_earliest_cancellation_date_later_than_end_date`\n- `support_contract_must_have_billing_group`\n- `support_contract_null_tier`\n- `team_limit_exceeded`\n- `team_names_must_be_unique`\n- `tenant_mismatch`\n- `topic_not_found`\n- `unable_to_parse_query`\n- `unit_cannot_be_moved_out_of_organization`\n- `unknown_user_sso_login_attempt`\n- `unsupported_resource_type`\n- `upgrade_pipeline_no_nodes`\n- `upgrade_pipeline_no_validation`\n- `upgrade_pipeline_not_enabled_for_project`\n- `upgrade_pipeline_service_not_destination`\n- `upgrade_pipeline_service_not_found`\n- `upgrade_step_destination_already_has_source`\n- `upgrade_step_destination_service_not_found`\n- `upgrade_step_exceeds_max_chain_length`\n- `upgrade_step_not_found`\n- `upgrade_step_service_type_mismatch`\n- `upgrade_step_source_service_not_found`\n- `upgrade_step_unsupported_service_type`\n- `upgrade_step_validation_not_possible_due_to_service_state`\n- `upgrade_step_would_create_cycle`\n- `upgrade_validation_already_exists`\n- `user_already_in_organization`\n- `user_already_invited_to_organization`\n- `user_cant_login`\n- `user_config_2fa_otp_verification_failed`\n- `user_deactivated`\n- `user_domain_does_not_belong_to_organization_or_no_linked_auth_method`\n- `user_group_names_must_be_unique`\n- `user_group_not_found`\n- `user_groups_belong_to_different_accounts`\n- `user_groups_must_be_from_same_account`\n- `user_has_no_access_to_billing_info`\n- `user_has_no_access_to_project_with_current_authentication_method`\n- `user_has_to_sign_in_with_non_account_authentication_method`\n- `user_has_too_many_disk_addition_requests`\n- `user_is_internal_user`\n- `user_not_account_owner`\n- `user_not_account_owner_of_billing_group`\n- `user_not_account_owner_of_parent_account`\n- `user_not_admin_of_account_billing_group`\n- `user_not_application_user`\n- `user_not_found`\n- `user_not_managed_by_organization`\n- `user_not_organization_admin`\n- `user_not_signed_in_with_account_authentication_method`\n- `user_oauth_authentication_method_not_allowed`\n- `user_password_authentication_method_not_allowed`\n- `user_password_compromised`\n- `user_password_not_found`\n- `user_personal_token_allowed_authentication_methods_cannot_be_disabled`\n- `user_personal_token_not_allowed`\n- `user_personal_tokens_cannot_be_disabled`\n- `user_role_not_allowed_to_perform_operation`\n- `user_saml_authentication_method_not_allowed`\n- `user_weblink_action_expired`\n- `username_is_invalid`\n- `username_is_reserved`\n- `users_belong_to_different_tenant_from_user_group_account`\n- `vcs_integration_installation_not_found_or_not_accessible`\n- `vcs_integration_not_found`\n- `vpc_id_and_subnet_id_required`\n- `webhook_invalid_event_data`\n- `webhook_unauthorized`\n"
servers:
- url: https://api.aiven.io/v1
tags:
- name: Service:_PostgreSQL
  x-displayName: 'Service: PostgreSQL'
paths:
  /account/{account_id}/pg/query/optimize:
    post:
      summary: Get query optimization recommendations for a query
      tags:
      - Service:_PostgreSQL
      operationId: PGAccountQueryOptimize
      x-badges:
      - name: Experimental
        position: after
        color: '#787885'
      x-experimental: true
      description: <p><blockquote>This endpoint <b>may be changed or removed at any time</b>. Don't use it in production environments.</blockquote><p>
      parameters:
      - $ref: '#/components/parameters/account_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PGAccountQueryOptimizeRequestBody'
            example:
              do_not_store: true
              flags: []
              pg_version: '16'
              query: Select email from users;
              schema_metadata: '{ ''columns'': [...], ''indexes'': [...], ''views'': [...], ... }'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PGAccountQueryOptimizeResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    title: Human readable error message
                  errors:
                    type: array
                    title: List of error details. Typically there is only one element
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          title: Human readable error message
                        error_code:
                          type: string
                          enum:
                          - optimization_failed
                          - unable_to_parse_query
                          title: Machine processable error code. Clients must be prepared to handle new codes.
                          description: 'optimization_failed: The service was unable to optimize the SQL query. unable_to_parse_query: The service could not parse the query due to syntax errors or unsupported expressions'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    title: Human readable error message
                  errors:
                    type: array
                    title: List of error details. Typically there is only one element
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          title: Human readable error message
                        error_code:
                          type: string
                          enum:
                          - account_not_found
                          title: Machine processable error code. Clients must be prepared to handle new codes.
                          description: 'account_not_found: No such account exists'
      security:
      - tokenAuth: []
        oauth2:
        - accounts:read
  /project/{project}/service/{service_name}/pg/available-extensions:
    get:
      summary: List PostgreSQL extensions that can be loaded with CREATE EXTENSION in this service
      tags:
      - Service:_PostgreSQL
      operationId: PGServiceAvailableExtensions
      parameters:
      - $ref: '#/components/parameters/project'
      - $ref: '#/components/parameters/service_name'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PGServiceAvailableExtensionsResponse'
      security:
      - tokenAuth: []
        oauth2:
        - services:read
  /pg/database-metadata-query:
    get:
      summary: Get the query used to retrieve schema metadata
      tags:
      - Service:_PostgreSQL
      operationId: PGServiceDatabaseMetadataQuery
      x-badges:
      - name: Experimental
        position: after
        color: '#787885'
      x-experimental: true
      description: <p><blockquote>This endpoint <b>may be changed or removed at any time</b>. Don't use it in production environments.</blockquote><p>
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PGServiceDatabaseMetadataQueryResponse'
  /pg/query/metadata-validate:
    post:
      summary: Validate schema metadata structure and statistics
      tags:
      - Service:_PostgreSQL
      operationId: PGServiceMetadataValidate
      x-badges:
      - name: Experimental
        position: after
        color: '#787885'
      x-experimental: true
      description: <p><blockquote>This endpoint <b>may be changed or removed at any time</b>. Don't use it in production environments.</blockquote><p>
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PGServiceMetadataValidateRequestBody'
            example:
              db_version: '16'
              metadata: '{ ''columns'': [...], ''indexes'': [...], ''views'': [...], ... }'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PGServiceMetadataValidateResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    title: Human readable error message
                  errors:
                    type: array
                    title: List of error details. Typically there is only one element
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          title: Human readable error message
                        error_code:
                          type: string
                          enum:
                          - metadata_validation_failed
                          title: Machine processable error code. Clients must be prepared to handle new codes.
                          description: 'metadata_validation_failed: Metadata validation failed'
  /project/{project}/service/{service_name}/pg/query/stats:
    post:
      summary: Fetch PostgreSQL service query statistics
      tags:
      - Service:_PostgreSQL
      operationId: PGServiceQueryStatistics
      parameters:
      - $ref: '#/components/parameters/project'
      - $ref: '#/components/parameters/service_name'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PGServiceQueryStatisticsRequestBody'
            example:
              limit: 100
              offset: 100
              order_by: calls:desc,total_time:asc
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PGServiceQueryStatisticsResponse'
      security:
      - tokenAuth: []
        oauth2:
        - services:read
  /project/{project}/service/{service_name}/query/stats:
    post:
      summary: 'Fetch PostgreSQL service query statistics (DEPRECATED: Use /project/$project/service/$service/pg/query/stats instead)'
      tags:
      - Service:_PostgreSQL
      operationId: PGServiceQueryStatisticsDeprecated
      deprecated: true
      description: '<p>DEPRECATED: Use /project/$project/service/$service/pg/query/stats instead</p>'
      parameters:
      - $ref: '#/components/parameters/project'
      - $ref: '#/components/parameters/service_name'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PGServiceQueryStatisticsDeprecatedResponse'
      security:
      - tokenAuth: []
        oauth2:
        - services:read
  /pg/query/validate:
    post:
      summary: Validate SQL query syntax
      tags:
      - Service:_PostgreSQL
      operationId: PGServiceQueryValidate
      x-badges:
      - name: Experimental
        position: after
        color: '#787885'
      x-experimental: true
      description: <p><blockquote>This endpoint <b>may be changed or removed at any time</b>. Don't use it in production environments.</blockquote><p>
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PGServiceQueryValidateRequestBody'
            example:
              do_not_store: true
              query: select email from users;
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PGServiceQueryValidateResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    title: Human readable error message
                  errors:
                    type: array
                    title: List of error details. Typically there is only one element
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          title: Human readable error message
                        error_code:
                          type: string
                          enum:
                          - query_validation_failed
                          title: Machine processable error code. Clients must be prepared to handle new codes.
                          description: 'query_validation_failed: Query validation failed'
  /project/{project}/service/{service_name}/connection_pool:
    post:
      summary: Create a new connection pool for service
      tags:
      - Service:_PostgreSQL
      operationId: ServicePGBouncerCreate
      parameters:
      - $ref: '#/components/parameters/project'
      - $ref: '#/components/parameters/service_name'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServicePGBouncerCreateRequestBody'
            example:
              database: testdb
              pool_mode: session
              pool_name: mypool-x-y-z
              pool_size: 50
              username: testuser
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePGBouncerCreateResponse'
      security:
      - tokenAuth: []
        oauth2:
        - services:write
  /project/{project}/service/{service_name}/connection_pool/{pool_name}:
    delete:
      summary: Delete a connection pool
      tags:
      - Service:_PostgreSQL
      operationId: ServicePGBouncerDelete
      parameters:
      - $ref: '#/components/parameters/project'
      - $ref: '#/components/parameters/service_name'
      - $ref: '#/components/parameters/pool_name'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePGBouncerDeleteResponse'
      security:
      - tokenAuth: []
        oauth2:
        - services:write
    put:
      summary: Update a connection pool
      tags:
      - Service:_PostgreSQL
      operationId: ServicePGBouncerUpdate
      parameters:
      - $ref: '#/components/parameters/project'
      - $ref: '#/components/parameters/service_name'
      - $ref: '#/components/parameters/pool_name'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServicePGBouncerUpdateRequestBody'
            example:
              database: testdb
              pool_mode: session
              pool_size: 50
              username: testuser
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePGBouncerUpdateResponse'
      security:
      - tokenAuth: []
        oauth2:
        - services:write
components:
  schemas:
    PGAccountQueryOptimizeResponse:
      type: object
      description: PGAccountQueryOptimizeResponse
      properties:
        optimize:
          type: object
          description: Optimize
          properties:
            existing_recommended_indexes:
              type: array
              description: Existing Recommended Indexes
              items:
                type: object
                properties:
                  index_definition:
                    type: string
                    description: Index definition
                required:
                - index_definition
            index_recommendations:
              type: array
              description: Index Recommendations
              items:
                type: object
                properties:
                  creation_cmd:
                    type: string
                    description: Creation command
                  table_name:
                    type: string
                    description: Table name
                required:
                - creation_cmd
                - table_name
            optimization_id:
              type: string
              description: Optimization ID
            optimized_query:
              type: string
              description: Optimized query in base64 format
            original_query:
              type: string
              description: Original query in base64 format
            recommendations:
              type: array
              description: Recommendations
              items:
                type: object
                properties:
                  bad_practice_sample:
                    type: string
                    description: Bad practice sample
                  best_practice_sample:
                    type: string
                    description: Best practice sample
                  description:
                    type: string
                    description: Description
                  fixable:
                    type: boolean
                    description: Fixable
                  line_number:
                    type: integer
                    description: Line number
                  priority:
                    type: integer
                    description: Priority
                  title:
                    type: string
                    description: Title
                  type:
                    type: integer
                    description: Type
                required:
                - bad_practice_sample
                - best_practice_sample
                - description
                - fixable
                - line_number
                - priority
                - title
                - type
          required:
          - existing_recommended_indexes
          - index_recommendations
          - optimized_query
          - original_query
          - recommendations
      required:
      - optimize
    ServicePGBouncerUpdateResponse:
      type: object
      description: ServicePGBouncerUpdateResponse
      properties:
        errors:
          type: array
          description: List of errors occurred during request processing
          items:
            type: object
            properties:
              message:
                type: string
                description: Printable error message
              more_info:
                type: string
                description: URL to the documentation of the error
              status:
                type: integer
                description: HTTP error status code
            required:
            - message
            - status
        message:
          type: string
          description: Printable result of the request
    PGServiceAvailableExtensionsResponse:
      type: object
      description: PGServiceAvailableExtensionsResponse
      properties:
        errors:
          type: array
          description: List of errors occurred during request processing
          items:
            type: object
            properties:
              message:
                type: string
                description: Printable error message
              more_info:
                type: string
                description: URL to the documentation of the error
              status:
                type: integer
                description: HTTP error status code
            required:
            - message
            - status
        extensions:
          type: array
          description: Extensions available for loading with CREATE EXTENSION in this service
          items:
            type: object
            properties:
              default_version:
                type: string
                description: Default version
              name:
                type: string
                description: Extension name
              versions:
                type: array
                description: Extension versions available
                items:
                  type: string
            required:
            - name
        message:
          type: string
          description: Printable result of the request
      required:
      - extensions
    PGServiceDatabaseMetadataQueryResponse:
      type: object
      description: PGServiceDatabaseMetadataQueryResponse
      properties:
        metadata_query:
          type: string
          description: Database metadata retrieval query
      required:
      - metadata_query
    ServicePGBouncerCreateRequestBody:
      type: object
      description: ServicePGBouncerCreateRequestBody
      properties:
        database:
          type: string
          maxLength: 63
          description: Service database name
        pool_mode:
          type: string
          description: PGBouncer pool mode
          default: transaction
          enum:
          - session
          - transaction
          - statement
        pool_name:
          type: string
          maxLength: 63
          description: Connection pool name
        pool_size:
          type: integer
          minimum: 1
          maximum: 10000
          description: Size of PGBouncer's PostgreSQL side connection pool
          default: 10
        username:
          type: string
          maxLength: 64
          description: Service username
      required:
      - database
      - pool_name
    ServicePGBouncerCreateResponse:
      type: object
      description: ServicePGBouncerCreateResponse
      properties:
        errors:
          type: array
          description: List of errors occurred during request processing
          items:
            type: object
            properties:
              message:
                type: string
                description: Printable error message
              more_info:
                type: string
                description: URL to the documentation of the error
              status:
                type: integer
                description: HTTP error status code
            required:
            - message
            - status
        message:
          type: string
          description: Printable result of the request
    PGServiceQueryStatisticsDeprecatedResponse:
      type: object
      description: PGServiceQueryStatisticsDeprecatedResponse
      properties:
        errors:
          type: array
          description: List of errors occurred during request processing
          items:
            type: object
            properties:
              message:
                type: string
                description: Printable error message
              more_info:
                type: string
                description: URL to the documentation of the error
              status:
                type: integer
                description: HTTP error status code
            required:
            - message
            - status
        message:
          type: string
          description: Printable result of the request
        queries:
          type: array
          description: List of query statistics
          items:
            type: object
            properties:
              blk_read_time:
                type: number
                description: Query statistic
              blk_write_time:
                type: number
                description: Query statistic
              calls:
                type: number
                description: Query statistic
              database_name:
                type: string
                description: Query statistic
              local_blks_dirtied:
                type: number
                description: Query statistic
              local_blks_hit:
                type: number
                description: Query statistic
              local_blks_read:
                type: number
                description: Query statistic
              local_blks_written:
                type: number
                description: Query statistic
              max_plan_time:
                type: number
                description: Query statistic
              max_time:
                type: number
                description: Query statistic
              mean_plan_time:
                type: number
                description: Query statistic
              mean_time:
                type: number
                description: Query statistic
              min_plan_time:
                type: number
                description: Query statistic
              min_time:
                type: number
                description: Query statistic
              query:
                type: string
                description: Query statistic
              queryid:
                type: number
                description: Query statistic
              rows:
                type: number
                description: Query statistic
              shared_blks_dirtied:
                type: number
                description: Query statistic
              shared_blks_hit:
                type: number
                description: Query statistic
              shared_blks_read:
                type: number
                description: Query statistic
              shared_blks_written:
                type: number
                description: Query statistic
              stddev_plan_time:
                type: number
                description: Query statistic
              stddev_time:
                type: number
                description: Query statistic
              temp_blks_read:
                type: number
                description: Query statistic
              temp_blks_written:
                type: number
                description: Query statistic
              total_plan_time:
                type: number
                description: Query statistic
              total_time:
                type: number
                description: Query statistic
              user_name:
                type: string
                description: Query statistic
              wal_bytes:
                type: string
                description: Query statistic
              wal_fpi:
                type: number
                description: Query statistic
              wal_records:
                type: number
                description: Query statistic
      required:
      - queries
    PGServiceQueryValidateResponse:
      type: object
      description: PGServiceQueryValidateResponse
      properties:
        status:
          type: string
          description: Status
      required:
      - status
    ServicePGBouncerUpdateRequestBody:
      type: object
      description: ServicePGBouncerUpdateRequestBody
      properties:
        database:
          type: string
          maxLength: 63
          description: Service database name
        pool_mode:
          type: string
          description: PGBouncer pool mode
          enum:
          - session
          - transaction
          - statement
        pool_size:
          type: integer
          minimum: 1
          maximum: 10000
          description: Size of PGBouncer's PostgreSQL side connection pool
        username:
          type: string
          maxLength: 64
          description: Service username
    PGServiceQueryValidateRequestBody:
      type: object
      description: PGServiceQueryValidateRequestBody
      properties:
        do_not_store:
          type: boolean
          description: Do not store details
          default: false
        query:
          type: string
          description: Query
      required:
      - query
    PGAccountQueryOptimizeRequestBody:
      type: object
      description: PGAccountQueryOptimizeRequestBody
      properties:
        do_not_store:
          type: boolean
          description: Do not store details
          default: false
        flags:
          type: array
          description: Optimization flags
          items:
            type: string
        pg_version:
          type: string
          description: An enumeration.
          title: PostgreSQL version
          enum:
          - '18'
          - '17'
          - '16'
          - '15'
          - '14'
          - '13'
          - '12'
          - '11'
          - '10'
          - '9'
          - '8'
          - '7'
        query:
          type: string
          description: Query
        schema_metadata:
          type: string
          description: Schema metadata
      required:
      - flags
      - pg_version
      - query
    PGServiceMetadataValidateResponse:
      type: object
      description: PGServiceMetadataValidateResponse
      properties:
        status:
          type: string
          description: Status
      required:
      - status
    PGServiceQueryStatisticsResponse:
      type: object
      description: PGServiceQueryStatisticsResponse
      properties:
        errors:
          type: array
          description: List of errors occurred during request processing
          items:
            type: object
            properties:
              message:
                type: string
                description: Printable error message
              more_info:
                type: string
                description: URL to the documentation of the error
              status:
                type: integer
                description: HTTP error status code
            required:
            - message
            - status
        message:
          type: string
          description: Printable result of the request
        queries:
          type: array
          description: List of query statistics
          items:
            type: object
            properties:
              blk_read_time:
                type: number
                description: Query statistic
              blk_write_time:
                type: number
                description: Query statistic
              calls:
                type: number
                description: Query statistic
              database_name:
                type: string
                description: Query statistic
              local_blks_dirtied:
                type: number
                description: Query statistic
              local_blks_hit:
                type: number
                description: Query statistic
              local_blks_read:
                type: number
                description: Query statistic
              local_blks_written:
                type: number
                description: Query statistic
              max_plan_time:
                type: number
                description: Query statistic
              max_time:
                type: number
                description: Query statistic
              mean_plan_time:
                type: number
                description: Query statistic
              mean_time:
                type: number
                description: Query statistic
              min_plan_time:
                type: number
                description: Query statistic
              min_time:
                type: number
                description: Query statistic
              query:
                type: string
                description: Query statistic
              queryid:
                type: number
                description: Query statistic
              rows:
                type: number
                description: Query statistic
              shared_blks_dirtied:
                type: number
                description: Query statistic
              shared_blks_hit:
                type: number
                description: Query statistic
              shared_blks_read:
                type: number
                description: Query statistic
              shared_blks_written:
                type: number
                description: Query statistic
              stddev_plan_time:
                type: number
                description: Query statistic
              stddev_time:
                type: number
                description: Query statistic
              temp_blks_read:
                type: number
                description: Query statistic
              temp_blks_written:
                type: number
                description: Query statistic
              total_plan_time:
                type: number
                description: Query statistic
              total_time:
                type: number
                description: Query statistic
              user_name:
                type: string
                description: Query statistic
              wal_bytes:
                type: string
                description: Query statistic
              wal_fpi:
                type: number
                description: Query statistic
              wal_records:
                type: number
                description: Query statistic
      required:
      - queries
    PGServiceMetadataValidateRequestBody:
      type: object
      description: PGServiceMetadataValidateRequestBody
      properties:
        db_version:
          type: string
          description: Database version
        metadata:
          type: string
          description: Metadata to validate
      required:
      - db_version
      - metadata
    PGServiceQueryStatisticsRequestBody:
      type: object
      description: PGServiceQueryStatisticsRequestBody
      properties:
        limit:
          type: integer
          minimum: 1
          maximum: 5000
          description: Limit for number of results
          default: 100
        offset:
          type: integer
          minimum: 0
          description: Offset for retrieved results based on sort order
          default: 0
        order_by:
          type: string
          maxLength: 256
          description: 'Sort order can be either asc or desc and multiple comma separated columns with their own order can be specified: :asc,:desc. Accepted sort columns are: blk_read_time, blk_write_time, calls, database_name, local_blks_dirtied, local_blks_hit, local_blks_read, local_blks_written, max_plan_time, max_time, mean_plan_time, mean_time, min_plan_time, min_time, query, queryid, rows, shared_blks_dirtied, shared_blks_hit, shared_blks_read, shared_blks_written, stddev_plan_time, stddev_time, temp_blks_read, temp_blks_written, total_plan_time, total_time, user_name, wal_bytes, wal_fpi, wal_records'
          title: Order in which to sort retrieved results
          default: calls:desc
    ServicePGBouncerDeleteResponse:
      type: object
      description: ServicePGBouncerDeleteResponse
      properties:
        errors:
          type: array
          description: List of errors occurred during request processing
          items:
            type: object
            properties:
              message:
                type: string
                description: Printable error message
              more_info:
                type: string
                description: URL to the documentation of the error
              status:
                type: integer
                description: HTTP error status code
            required:
            - message
            - status
        message:
          type: string
          description: Printable result of the request
  parameters:
    account_id:
      in: path
      name: account_id
      description: Account ID
      schema:
        type: string
      required: true
    service_name:
      in: path
      name: service_name
      description: Service name
      schema:
        type: string
      required: true
    pool_name:
      in: path
      name: pool_name
      description: PgBouncer connection pool name
      schema:
        type: string
      required: true
    project:
      in: path
      name: project
      description: Project name
      schema:
        type: string
      required: true
  securitySchemes:
    tokenAuth:
      description: 'Header should be of the format `authorization: aivenv1 <TOKEN>`. Tokens can be obtained from [your Aiven profile page](https://console.aiven.io/profile/auth)'
      scheme: bearer
      type: http
    oauth2:
      type: oauth2
      description: OAuth2 security scheme
      flows:
        authorizationCode:
          authorizationUrl: https://console.aiven.io/oauth/authorize
          tokenUrl: https://api.aiven.io/v1/oauth2/token
          scopes:
            all: Provide full access to the API
            accounts: Allow enumerating and reading accounts configuration
            accounts:read: Allow modifying account configuration
            accounts:write: Provides full access to authentication related API
            authentication: Provides full access to authentication related API
            authentication:read: Allow reading authentication related configuration on resources (user profile, accounts)
            authentication:write: Allow modifying authentication related configurations on resources (user profile, accounts)
            billing: Provide full access to billing APIs
            billing:read: Allow reading billing information and configuration
            billing:write: Allow writing billing configuration
            payments: Provide full access to payment method APIs
            payments:read: Allow reading the payment method configurations
            payments:write: Allows writing payment method configuration
            privatelink: Provide full access to private link APIs
            privatelink:read: Allow enumerating and reading private link items and configurations
            privatelink:write: Allow writing (creating, modifying, deleting) private link items
            projects: Provide full access to projects APIs
            projects:read: Allow enumerating projects and reading their configuration
            projects:write: Allow writing (creating, modifying, deleting) projects
            scim: Provide full access to SCIM operations
            scim:read: Allow reading SCIM endpoints
            scim:write: Allow writing (modifying) SCIM endpoints
            services: Provide full access to services APIs
            services:read: Allow enumerating services and reading their configuration
            services:write: Allow writing (creating, modifying, deleting) services
            static_ips: Provide full access to static IPs APIs
            static_ips:read: Allow enumerating and reading static IP items and configurations
            static_ips:write: Allow writing (creating, modifying, deleting) static IP items
            tickets: Provide full access to support ticket APIs
            tickets:read: Allow enumerating and reading support tickets
            tickets:write: Allow writing (creating, modifying) support tickets
            user: Provide full access to user profile APIs
            user:read: Allow reading user profile and configuration
            user:write: Allow writing (modifying) user profile and configuration
externalDocs:
  description: Aiven CLI client
  url: https://github.com/aiven/aiven-client