openapi: 3.0.3
info:
  description: API for managing resources on Ubicloud
  title: Clover API
  version: 0.1.0
  contact:
    url: https://www.ubicloud.com/
    email: support@ubicloud.com
  license:
    name: GNU Affero General Public License v3.0 (AGPL-3.0)
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
servers:
  - url: https://api.ubicloud.com
paths:
  /project:
    get:
      operationId: listProjects
      summary: List all projects
      parameters:
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/Projects'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Project
    post:
      operationId: createProject
      summary: Create a new project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: my-project-name
              additionalProperties: false
              required:
                - name
      responses:
        '200':
          $ref: '#/components/responses/Project'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Project
  /project/{project_id}:
    parameters:
      - $ref: '#/components/parameters/project_id'
    delete:
      operationId: deleteProject
      summary: Delete a project
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Project
    get:
      operationId: getProject
      summary: Retrieve a project
      responses:
        '200':
          $ref: '#/components/responses/Project'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Project
  /project/{project_id}/audit-log:
    parameters:
      - $ref: '#/components/parameters/project_id'
    get:
      operationId: searchProjectAuditLog
      summary: Search project audit log entries
      parameters:
        - name: action
          in: query
          description: Filter by action type
          required: false
          schema:
            type: string
          example: vm, create, vm/create
        - name: end
          in: query
          description: Filter by end_date (shows 3 months prior)
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Limit the number of returned records (1-1000)
          required: false
          schema:
            type: number
        - name: subject
          in: query
          description: Filter by account name/email/ID
          required: false
          schema:
            type: string
        - name: object
          in: query
          description: Filter by object ID
          required: false
          schema:
            type: string
        - name: pagination_key
          in: query
          description: Key for paginating results
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/AuditLogs'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Audit Log
  /project/{project_id}/firewall:
    parameters:
      - $ref: '#/components/parameters/project_id'
    get:
      operationId: getFirewall
      summary: List all firewalls
      responses:
        '200':
          $ref: '#/components/responses/Firewalls'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Firewall
  /project/{project_id}/github:
    parameters:
      - $ref: '#/components/parameters/project_id'
    get:
      operationId: getGithubInstallations
      summary: List all GitHub installations
      responses:
        '200':
          $ref: '#/components/responses/GithubInstallations'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - GitHub
  /project/{project_id}/github/{github_installation_reference}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/github_installation_reference'
    get:
      operationId: getGithubInstallation
      summary: Get GitHub installation details
      responses:
        '200':
          $ref: '#/components/responses/GithubInstallation'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - GitHub
  /project/{project_id}/github/{github_installation_reference}/repository:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/github_installation_reference'
    get:
      operationId: getGithubInstallationRepositories
      summary: List repositories for a GitHub installation
      responses:
        '200':
          $ref: '#/components/responses/GithubRepositories'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - GitHub
  /project/{project_id}/github/{github_installation_reference}/repository/{github_repository_reference}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/github_installation_reference'
      - $ref: '#/components/parameters/github_repository_reference'
    get:
      operationId: getGithubRepository
      summary: Get GitHub repository details
      responses:
        '200':
          $ref: '#/components/responses/GithubRepository'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - GitHub
  /project/{project_id}/github/{github_installation_reference}/repository/{github_repository_reference}/cache:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/github_installation_reference'
      - $ref: '#/components/parameters/github_repository_reference'
    get:
      operationId: getGithubCacheEntries
      summary: List all cache entries for a GitHub repository
      responses:
        '200':
          $ref: '#/components/responses/GithubCacheEntries'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - GitHub
    delete:
      operationId: deleteAllGithubCacheEntries
      summary: Delete all cache entries for a GitHub repository
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - GitHub
  /project/{project_id}/github/{github_installation_reference}/repository/{github_repository_reference}/cache/{github_cache_entry_id}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/github_installation_reference'
      - $ref: '#/components/parameters/github_repository_reference'
      - $ref: '#/components/parameters/github_cache_entry_id'
    get:
      operationId: getGithubCacheEntry
      summary: Get cache entry details
      responses:
        '200':
          $ref: '#/components/responses/GithubCacheEntry'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - GitHub
    delete:
      operationId: deleteGithubCacheEntry
      summary: Delete a cache entry
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - GitHub
  /project/{project_id}/inference-api-key:
    parameters:
      - $ref: '#/components/parameters/project_id'
    get:
      operationId: getInferenceApiKeys
      summary: List all inference API keys
      responses:
        '200':
          $ref: '#/components/responses/InferenceApiKeys'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Inference Api Key
    post:
      operationId: createInferenceApiKey
      summary: Create a new inference API key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
              additionalProperties: false
      responses:
        '200':
          $ref: '#/components/responses/InferenceApiKey'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Inference Api Key
  /project/{project_id}/inference-api-key/{inference_api_key_id}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/inference_api_key_id'
    get:
      operationId: getInferenceApiKey
      summary: Get inference API key details
      responses:
        '200':
          $ref: '#/components/responses/InferenceApiKey'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Inference Api Key
    delete:
      operationId: deleteInferenceApiKey
      summary: Delete a specific inference API key
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Inference Api Key
  /project/{project_id}/inference-endpoint:
    parameters:
      - $ref: '#/components/parameters/project_id'
    get:
      operationId: listInferenceEndpoints
      summary: List all inference endpoints
      responses:
        '200':
          $ref: '#/components/responses/InferenceEndpoints'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Inference Endpoint
  /project/{project_id}/kubernetes-cluster:
    get:
      operationId: listProjectKubernetesClusters
      summary: List all kubernetes clusters
      parameters:
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/KubernetesClusters'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Kubernetes Cluster
  /project/{project_id}/load-balancer:
    get:
      operationId: listLoadBalancers
      summary: List all load balancers
      parameters:
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/LoadBalancers'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Load Balancer
  /project/{project_id}/location/{location}/firewall:
    parameters:
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/project_id'
    get:
      operationId: getLocationFirewall
      summary: List firewalls in a location
      responses:
        '200':
          $ref: '#/components/responses/Firewalls'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Firewall
  /project/{project_id}/location/{location}/firewall/{firewall_reference}:
    parameters:
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/firewall_reference'
    delete:
      operationId: deleteLocationFirewall
      summary: Delete a firewall
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Firewall
    get:
      operationId: getLocationFirewallDetails
      summary: Get firewall details
      responses:
        '200':
          $ref: '#/components/responses/FirewallDetailed'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Firewall
    post:
      operationId: createLocationFirewall
      summary: Create a new firewall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  description: Description of the firewall
                  type: string
              additionalProperties: false
      responses:
        '200':
          $ref: '#/components/responses/Firewall'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Firewall
    patch:
      operationId: updateFirewall
      summary: Update a firewall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  description: New description for firewall
                  type: string
              additionalProperties: false
              required:
                - description
      responses:
        '200':
          $ref: '#/components/responses/Firewall'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Firewall
  /project/{project_id}/location/{location}/firewall/{firewall_reference}/attach-subnet:
    parameters:
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/firewall_reference'
    post:
      operationId: actionLocationFirewallAttachSubnet
      summary: Attach a subnet to firewall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                private_subnet_id:
                  description: Private subnet id to attach
                  type: string
              additionalProperties: false
              required:
                - private_subnet_id
      responses:
        '200':
          $ref: '#/components/responses/FirewallDetailed'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Firewall
  /project/{project_id}/location/{location}/firewall/{firewall_reference}/detach-subnet:
    parameters:
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/firewall_reference'
    post:
      operationId: actionLocationFirewallDetachSubnet
      summary: Detach a subnet from firewall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                private_subnet_id:
                  description: Private subnet id to detach
                  type: string
              additionalProperties: false
              required:
                - private_subnet_id
      responses:
        '200':
          $ref: '#/components/responses/FirewallDetailed'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Firewall
  /project/{project_id}/location/{location}/firewall/{firewall_reference}/firewall-rule:
    parameters:
      - $ref: '#/components/parameters/firewall_reference'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/project_id'
    post:
      operationId: createLocationFirewallRule
      summary: Create a new firewall rule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                cidr:
                  description: CIDR or private subnet id or name to allow
                  type: string
                firewall_id:
                  type: string
                port_range:
                  description: Port range to allow
                  type: string
                protocol:
                  description: Protocol to allow (tcp or udp, default tcp)
                  type: string
                description:
                  description: Description to use for the firewall rule
                  type: string
                project_id:
                  type: string
              additionalProperties: false
              required:
                - cidr
      responses:
        '200':
          $ref: '#/components/responses/FirewallRuleOrRules'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Firewall Rule
  /project/{project_id}/location/{location}/firewall/{firewall_reference}/firewall-rule/{firewall_rule_id}:
    parameters:
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/firewall_reference'
      - $ref: '#/components/parameters/firewall_rule_id'
    delete:
      operationId: deleteLocationFirewallFirewallRule
      summary: Delete a firewall rule
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Firewall Rule
    get:
      operationId: getLocationFirewallFirewallRuleDetails
      summary: Get firewall rule details
      responses:
        '200':
          $ref: '#/components/responses/FirewallRule'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Firewall Rule
    patch:
      operationId: modifyFirewallRule
      summary: Modify a firewall rule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FirewallRuleUpdate'
      responses:
        '200':
          $ref: '#/components/responses/FirewallRule'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Firewall Rule
  /project/{project_id}/location/{location}/firewall/{firewall_reference}/rename:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/firewall_reference'
    post:
      operationId: renameFirewall
      summary: Rename a firewall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: New name for firewall
                  type: string
              additionalProperties: false
              required:
                - name
      responses:
        '200':
          $ref: '#/components/responses/Firewall'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Firewall
  /project/{project_id}/location/{location}/kubernetes-cluster:
    get:
      operationId: listLocationKubernetesClusters
      summary: List kubernetes clusters in a location
      parameters:
        - $ref: '#/components/parameters/location'
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/KubernetesClusters'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Kubernetes Cluster
  /project/{project_id}/location/{location}/kubernetes-cluster/{kubernetes_cluster_reference}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/kubernetes_cluster_reference'
    delete:
      operationId: deleteKubernetesCluster
      summary: Delete a kubernetes cluster
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Kubernetes Cluster
    get:
      operationId: getKubernetesClusterDetails
      summary: Get kubernetes cluster details
      responses:
        '200':
          $ref: '#/components/responses/KubernetesCluster'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Kubernetes Cluster
    post:
      operationId: createKubernetesCluster
      summary: Create a new kubernetes cluster
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  description: Version of the kubernetes cluster
                  type: string
                worker_size:
                  description: Size of each worker VM
                  type: string
                cp_nodes:
                  description: Number of control plane nodes
                  type: integer
                worker_nodes:
                  description: Number of worker nodes
                  type: integer
              additionalProperties: false
              required:
                - version
                - worker_size
      responses:
        '200':
          $ref: '#/components/responses/KubernetesCluster'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Kubernetes Cluster
  /project/{project_id}/location/{location}/kubernetes-cluster/{kubernetes_cluster_reference}/kubeconfig:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/kubernetes_cluster_reference'
    get:
      operationId: getKubernetesKubeconfigFile
      summary: Get kubeconfig file
      responses:
        '200':
          $ref: '#/components/responses/Kubeconfig'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Kubernetes Cluster
  /project/{project_id}/location/{location}/kubernetes-cluster/{kubernetes_cluster_reference}/node/{kubernetes_node_name}/retire:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/kubernetes_cluster_reference'
      - $ref: '#/components/parameters/kubernetes_node_name'
    post:
      operationId: retireKubernetesNode
      summary: Retire a worker node from a kubernetes cluster
      responses:
        '200':
          $ref: '#/components/responses/KubernetesNodepool'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Kubernetes Cluster
  /project/{project_id}/location/{location}/kubernetes-cluster/{kubernetes_cluster_reference}/nodepool:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/kubernetes_cluster_reference'
    post:
      operationId: createKubernetesNodepool
      summary: Create a new kubernetes nodepool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Name of the nodepool
                  type: string
                node_count:
                  description: Number of worker nodes in the nodepool
                  type: integer
                node_size:
                  description: Size of each worker node
                  type: string
              additionalProperties: false
              required:
                - name
                - node_count
                - node_size
      responses:
        '200':
          $ref: '#/components/responses/KubernetesNodepool'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Kubernetes Cluster
  /project/{project_id}/location/{location}/kubernetes-cluster/{kubernetes_cluster_reference}/nodepool/{kubernetes_nodepool_reference}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/kubernetes_cluster_reference'
      - $ref: '#/components/parameters/kubernetes_nodepool_reference'
    delete:
      operationId: deleteKubernetesNodepool
      summary: Delete a kubernetes nodepool
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Kubernetes Cluster
  /project/{project_id}/location/{location}/kubernetes-cluster/{kubernetes_cluster_reference}/nodepool/{kubernetes_nodepool_reference}/rename:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/kubernetes_cluster_reference'
      - $ref: '#/components/parameters/kubernetes_nodepool_reference'
    post:
      operationId: renameKubernetesNodepool
      summary: Rename a kubernetes nodepool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: New name for kubernetes nodepool
                  type: string
              additionalProperties: false
              required:
                - name
      responses:
        '200':
          $ref: '#/components/responses/KubernetesNodepool'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Kubernetes Cluster
  /project/{project_id}/location/{location}/kubernetes-cluster/{kubernetes_cluster_reference}/nodepool/{kubernetes_nodepool_reference}/resize:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/kubernetes_cluster_reference'
      - $ref: '#/components/parameters/kubernetes_nodepool_reference'
    post:
      operationId: resizeKubernetesNodepool
      summary: Change number of nodes of a kubernetes nodepool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                node_count:
                  description: New number of nodes for the kubernetes nodepool
                  type: integer
              additionalProperties: false
              required:
                - node_count
      responses:
        '200':
          $ref: '#/components/responses/KubernetesNodepool'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Kubernetes Cluster
  /project/{project_id}/location/{location}/kubernetes-cluster/{kubernetes_cluster_reference}/nodepool/{kubernetes_nodepool_reference}/upgrade:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/kubernetes_cluster_reference'
      - $ref: '#/components/parameters/kubernetes_nodepool_reference'
    post:
      operationId: upgradeKubernetesNodepool
      summary: Upgrade a kubernetes nodepool to the cluster version
      responses:
        '200':
          $ref: '#/components/responses/KubernetesNodepool'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Kubernetes Cluster
  /project/{project_id}/location/{location}/kubernetes-cluster/{kubernetes_cluster_reference}/rename:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/kubernetes_cluster_reference'
    post:
      operationId: renameKubernetesCluster
      summary: Rename a kubernetes cluster
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: New name for kubernetes cluster
                  type: string
              additionalProperties: false
              required:
                - name
      responses:
        '200':
          $ref: '#/components/responses/KubernetesCluster'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Kubernetes Cluster
  /project/{project_id}/location/{location}/kubernetes-cluster/{kubernetes_cluster_reference}/upgrade:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/kubernetes_cluster_reference'
    post:
      operationId: upgradeKubernetesCluster
      summary: Upgrade a kubernetes cluster
      responses:
        '200':
          $ref: '#/components/responses/KubernetesCluster'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Kubernetes Cluster
  /project/{project_id}/location/{location}/load-balancer:
    get:
      operationId: listLocationLoadBalancers
      summary: List load balancers in a location
      parameters:
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/location'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/LoadBalancers'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Load Balancer
  /project/{project_id}/location/{location}/load-balancer/{load_balancer_reference}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/load_balancer_reference'
    delete:
      operationId: deleteLoadBalancer
      summary: Delete a load balancer
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Load Balancer
    get:
      operationId: getLoadBalancerDetails
      summary: Get load balancer details
      responses:
        '200':
          $ref: '#/components/responses/LoadBalancer'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Load Balancer
    patch:
      operationId: patchLocationLoadBalancer
      summary: Update a load balancer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                algorithm:
                  description: Algorithm of the Load Balancer
                  type: string
                stack:
                  description: Networking stack of the Load Balancer (ipv4, ipv6, or dual)
                  type: string
                dst_port:
                  description: Destination port for the Load Balancer
                  type: integer
                health_check_endpoint:
                  description: Health check endpoint URL
                  type: string
                src_port:
                  description: Source port for the Load Balancer
                  type: integer
                vms:
                  description: List of VM apids for the Load Balancer
                  type: array
                  items:
                    type: string
                cert_enabled:
                  description: Whether SSL certificates are enabled for the Load Balancer
                  type: boolean
                  nullable: true
              additionalProperties: false
              required:
                - algorithm
                - dst_port
                - health_check_endpoint
                - src_port
                - vms
      responses:
        '200':
          $ref: '#/components/responses/LoadBalancer'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Load Balancer
    post:
      operationId: createLocationLoadBalancer
      summary: Create a new load balancer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                algorithm:
                  description: Algorithm of the Load Balancer
                  type: string
                stack:
                  description: Networking stack of the Load Balancer (ipv4, ipv6, or dual)
                  type: string
                dst_port:
                  description: Destination port for the Load Balancer
                  type: integer
                health_check_endpoint:
                  description: Health check endpoint URL
                  type: string
                health_check_protocol:
                  description: Health check endpoint protocol
                  type: string
                private_subnet_id:
                  description: ID of Private Subnet
                  type: string
                src_port:
                  description: Source port for the Load Balancer
                  type: integer
                cert_enabled:
                  description: Whether SSL certificates are enabled for the Load Balancer
                  type: boolean
              additionalProperties: false
              required:
                - algorithm
                - dst_port
                - health_check_protocol
                - private_subnet_id
                - src_port
      responses:
        '200':
          $ref: '#/components/responses/LoadBalancer'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Load Balancer
  /project/{project_id}/location/{location}/load-balancer/{load_balancer_reference}/attach-vm:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/load_balancer_reference'
    post:
      operationId: attachVmLocationLoadBalancer
      summary: Attach a VM to a load balancer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vm_id:
                  description: Apid of VM to attach to Load Balancer
                  type: string
              additionalProperties: false
              required:
                - vm_id
      responses:
        '200':
          $ref: '#/components/responses/LoadBalancer'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Load Balancer
  /project/{project_id}/location/{location}/load-balancer/{load_balancer_reference}/detach-vm:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/load_balancer_reference'
    post:
      operationId: detachVmLocationLoadBalancer
      summary: Detach a VM from a load balancer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vm_id:
                  description: Apid of VM to detach from Load Balancer
                  type: string
              additionalProperties: false
              required:
                - vm_id
      responses:
        '200':
          $ref: '#/components/responses/LoadBalancer'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Load Balancer
  /project/{project_id}/location/{location}/load-balancer/{load_balancer_reference}/rename:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/load_balancer_reference'
    post:
      operationId: renameLoadBalancer
      summary: Rename a load balancer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: New name for load balancer
                  type: string
              additionalProperties: false
              required:
                - name
      responses:
        '200':
          $ref: '#/components/responses/LoadBalancer'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Load Balancer
  /project/{project_id}/location/{location}/load-balancer/{load_balancer_reference}/toggle-ssl-certificate:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/load_balancer_reference'
    post:
      operationId: toggleSslCertificateLoadBalancer
      summary: Toggle the SSL certificate for a load balancer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                cert_enabled:
                  description: Whether SSL certificates are enabled for the Load Balancer
                  type: boolean
              additionalProperties: false
              required:
                - cert_enabled
      responses:
        '200':
          $ref: '#/components/responses/LoadBalancer'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Load Balancer
  /project/{project_id}/location/{location}/machine-image:
    get:
      operationId: listLocationMachineImages
      summary: List machine images in a location
      parameters:
        - $ref: '#/components/parameters/location'
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/MachineImages'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Machine Image
  /project/{project_id}/location/{location}/machine-image/{machine_image_reference}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
    post:
      operationId: createMachineImage
      summary: Create a machine image from a stopped VM
      parameters:
        - $ref: '#/components/parameters/machine_image_new_name'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vm:
                  description: UBID of the source VM
                  type: string
                version:
                  description: Version label (default is a timestamp)
                  type: string
                destroy_source:
                  description: Destroy the source VM after capture
                  type: boolean
              additionalProperties: false
              required:
                - vm
      responses:
        '200':
          $ref: '#/components/responses/MachineImage'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Machine Image
    delete:
      operationId: deleteMachineImage
      summary: Delete a machine image
      parameters:
        - $ref: '#/components/parameters/machine_image_reference'
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Machine Image
    get:
      operationId: getMachineImage
      summary: Get details of a machine image
      parameters:
        - $ref: '#/components/parameters/machine_image_reference'
      responses:
        '200':
          $ref: '#/components/responses/MachineImage'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Machine Image
    patch:
      operationId: updateMachineImage
      summary: Update a machine image
      parameters:
        - $ref: '#/components/parameters/machine_image_reference'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                latest_version:
                  description: Version label to set as latest
                  type: string
              additionalProperties: false
              required:
                - latest_version
      responses:
        '200':
          $ref: '#/components/responses/MachineImage'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Machine Image
  /project/{project_id}/location/{location}/machine-image/{machine_image_reference}/rename:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/machine_image_reference'
    post:
      operationId: renameMachineImage
      summary: Rename a machine image
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: New name for the machine image
                  type: string
              additionalProperties: false
              required:
                - name
      responses:
        '200':
          $ref: '#/components/responses/MachineImage'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Machine Image
  /project/{project_id}/location/{location}/machine-image/{machine_image_reference}/version:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/machine_image_reference'
    get:
      operationId: listMachineImageVersions
      summary: List versions of a machine image
      responses:
        '200':
          $ref: '#/components/responses/MachineImageVersions'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Machine Image
  /project/{project_id}/location/{location}/machine-image/{machine_image_reference}/version/{version}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/machine_image_reference'
      - $ref: '#/components/parameters/machine_image_version'
    post:
      operationId: createMachineImageVersion
      summary: Create a new version of a machine image from a stopped VM
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vm:
                  description: UBID of the source VM
                  type: string
                destroy_source:
                  description: Destroy the source VM after capture
                  type: boolean
              additionalProperties: false
              required:
                - vm
      responses:
        '200':
          $ref: '#/components/responses/MachineImageVersion'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Machine Image
    delete:
      operationId: deleteMachineImageVersion
      summary: Delete a specific version of a machine image
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Machine Image
  /project/{project_id}/location/{location}/postgres:
    get:
      operationId: listLocationPostgresDatabases
      summary: List PostgreSQL databases in a location
      parameters:
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/location'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabases'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
    delete:
      operationId: deletePostgresDatabase
      summary: Delete a PostgreSQL database
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
    get:
      operationId: getPostgresDatabaseDetails
      summary: Get PostgreSQL database details
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
    post:
      operationId: createPostgresDatabase
      summary: Create a new PostgreSQL database
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                flavor:
                  description: Kind of database
                  type: string
                ha_type:
                  description: High availability type
                  type: string
                size:
                  description: Requested size for the underlying VM
                  type: string
                storage_size:
                  description: Requested storage size in GiB
                  type: integer
                version:
                  description: PostgreSQL version
                  type: string
                  enum:
                    - '16'
                    - '17'
                    - '18'
                restrict_by_default:
                  description: Whether to restrict access by default (if so, firewall rules must be added to access)
                  type: boolean
                private_subnet_name:
                  description: Name for the private subnet (if not provided, a name will be auto-generated)
                  type: string
                pg_config:
                  type: object
                  example:
                    max_connections: '100'
                  additionalProperties:
                    type: string
                pgbouncer_config:
                  type: object
                  example:
                    max_client_conn: '100'
                  additionalProperties:
                    type: string
                tags:
                  description: Tags for the Postgres Database
                  type: array
                  items:
                    $ref: '#/components/schemas/PostgresTag'
              additionalProperties: false
              required:
                - size
                - storage_size
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
    patch:
      operationId: patchPostgresDatabase
      summary: Update a PostgreSQL database
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ha_type:
                  description: High availability type
                  type: string
                size:
                  description: Requested size for the underlying VM
                  type: string
                storage_size:
                  description: Requested storage size in GiB
                  type: integer
                tags:
                  description: Tags for the Postgres Database
                  type: array
                  items:
                    $ref: '#/components/schemas/PostgresTag'
              additionalProperties: false
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/backup:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
    get:
      operationId: listPostgresDatabaseBackups
      summary: List backups for a specific PostgreSQL database
      responses:
        '200':
          $ref: '#/components/responses/PostgresBackups'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/ca-certificates:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
    get:
      operationId: getPostgresCACertificatesByName
      summary: Download CA certificates for a PostgreSQL database
      responses:
        '200':
          description: CA certificate file in pem format
          headers:
            Content-Disposition:
              schema:
                type: string
                example: attachment; filename="postgres-ca-certificate.pem"
          content:
            application/x-pem-file:
              schema:
                type: string
                format: binary
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/cert/add-auth-user:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: addCertAuthUser
      summary: Add provided name to list of users with certificate authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertAuthUserRequest'
      responses:
        '200':
          $ref: '#/components/responses/CertAuthUserList'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/cert/create-client-keypair:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: createClientCertKeypair
      summary: Create and return client certificate keypair with requested common name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                common_name:
                  description: CN for cert
                  type: string
                duration:
                  description: Duration before expiry, in seconds
                  type: integer
              additionalProperties: false
      responses:
        '200':
          description: certificate keypair file in pem format
          headers:
            Content-Disposition:
              schema:
                type: string
                example: attachment; filename="certificate-key.pem"
          content:
            application/x-pem-file:
              schema:
                type: string
                format: binary
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/cert/remove-auth-user:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: removeCertAuthUser
      summary: Remove provided name from list of users with certificate authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertAuthUserRequest'
      responses:
        '200':
          $ref: '#/components/responses/CertAuthUserList'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/config:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
    get:
      operationId: getPostgresDatabaseConfig
      summary: Get PostgreSQL database configuration
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostgresConfig'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
    post:
      operationId: updatePostgresDatabaseConfig
      summary: Replace PostgreSQL database configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostgresConfig'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostgresConfig'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
    patch:
      operationId: patchPostgresDatabaseConfig
      summary: Update PostgreSQL database configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostgresPatchConfig'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostgresConfig'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/firewall-rule:
    parameters:
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
      - $ref: '#/components/parameters/project_id'
    get:
      operationId: listLocationPostgresFirewallRules
      summary: List PostgreSQL firewall rules
      responses:
        '200':
          $ref: '#/components/responses/PostgresFirewallRules'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Firewall Rule
    post:
      operationId: createLocationPostgresFirewallRule
      summary: Create a new PostgreSQL firewall rule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                cidr:
                  description: CIDR of the firewall rule
                  type: string
                description:
                  description: Description of the firewall rule
                  type: string
                  nullable: true
              additionalProperties: false
              required:
                - cidr
      responses:
        '200':
          $ref: '#/components/responses/PostgresFirewallRule'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Firewall Rule
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/firewall-rule/{firewall_rule_id}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
      - $ref: '#/components/parameters/firewall_rule_id'
    patch:
      operationId: patchLocationPostgresFirewallRule
      summary: Update a PostgreSQL firewall rule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                cidr:
                  description: CIDR of the firewall rule
                  type: string
                  nullable: true
                description:
                  description: Description of the firewall rule
                  type: string
                  nullable: true
              additionalProperties: false
      responses:
        '200':
          $ref: '#/components/responses/PostgresFirewallRule'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Firewall Rule
    delete:
      operationId: deleteLocationPostgresFirewallRule
      summary: Delete a PostgreSQL firewall rule
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Firewall Rule
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/log-destination:
    parameters:
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
      - $ref: '#/components/parameters/project_id'
    post:
      operationId: createLocationPostgresLogDestination
      summary: Create a new PostgreSQL log destination
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Name for the Log Destination
                  type: string
                type:
                  description: Destination type. "otlp" sends via OTLP HTTP (https://...); "syslog" sends via RFC 5424 over TLS (tcp://host:port)
                  type: string
                  enum:
                    - otlp
                    - syslog
                url:
                  description: 'Endpoint URL. For otlp: https://... For syslog: tcp://host:port'
                  type: string
                options:
                  description: 'Authentication options. For otlp: {"headers": {"Header-Name": "value"}}. For syslog: {"structured_data": {"sd-id": {"key": "value"}}}'
                  type: object
              additionalProperties: false
              required:
                - name
                - type
                - url
      responses:
        '200':
          $ref: '#/components/responses/PostgresLogDestination'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Log Destination
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/log-destination/{log_destination_id}:
    parameters:
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/log_destination_id'
      - $ref: '#/components/parameters/postgres_database_reference'
      - $ref: '#/components/parameters/project_id'
    delete:
      operationId: deleteLocationPostgresLogDestination
      summary: Delete a specific log destination
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Log Destination
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/logs:
    parameters:
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
      - $ref: '#/components/parameters/project_id'
    get:
      operationId: getPostgresDatabaseLogs
      summary: Get PostgreSQL database logs
      parameters:
        - name: start
          in: query
          description: Start time for log query (rfc3339 format, default 30 minutes ago)
          required: false
          schema:
            type: string
            example: 2025-05-12T11:27:24+00:00
        - name: end
          in: query
          description: End time for log query (rfc3339 format, default now)
          required: false
          schema:
            type: string
            example: 2025-05-12T11:57:24+00:00
        - name: stream_name
          in: query
          description: Filter by log stream (postgres, pgbouncer, or upgrade)
          required: false
          schema:
            type: string
            example: postgres
            enum:
              - postgres
              - pgbouncer
              - upgrade
        - name: severity_level
          in: query
          description: Filter by log severity level
          required: false
          schema:
            type: string
            example: INFO
            enum:
              - DEBUG
              - INFO
              - WARN
              - ERROR
              - FATAL
        - name: server_role
          in: query
          description: Filter by server role (primary or standby)
          required: false
          schema:
            type: string
            example: primary
            enum:
              - primary
              - standby
        - name: query_pattern
          in: query
          description: Pattern for substring match against log message body
          required: false
          schema:
            type: string
        - name: max_log_lines
          in: query
          description: Number of log lines to return (default 50, max 500)
          required: false
          schema:
            type: integer
            default: 50
        - name: pagination_key
          in: query
          description: Pagination key returned from a previous response
          required: false
          schema:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabaseLogs'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/metric-destination:
    parameters:
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
      - $ref: '#/components/parameters/project_id'
    post:
      operationId: createLocationPostgresMetricDestination
      summary: Create a new PostgreSQL metric destination
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  description: Password for the Metric Destination
                  type: string
                url:
                  description: URL for the Metric Destination
                  type: string
                username:
                  description: Username for the Metric Destination
                  type: string
              additionalProperties: false
              required:
                - password
                - url
                - username
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Metric Destination
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/metric-destination/{metric_destination_id}:
    parameters:
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/metric_destination_id'
      - $ref: '#/components/parameters/postgres_database_reference'
      - $ref: '#/components/parameters/project_id'
    delete:
      operationId: deleteLocationPostgresMetricDestination
      summary: Delete a specific metric destination
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Metric Destination
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/metrics:
    parameters:
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
      - $ref: '#/components/parameters/project_id'
    get:
      operationId: getPostgresDatabaseMetrics
      summary: Get PostgreSQL database metrics
      parameters:
        - name: start
          in: query
          description: Start time for metrics query (rfc3339 format)
          required: false
          schema:
            type: string
            example: 2025-05-12T11:57:24+00:00
            default: now-30m
        - name: end
          in: query
          description: End time for metrics query (rfc3339 format)
          required: false
          schema:
            type: string
            example: 2025-05-12T11:27:24+00:00
            default: now
        - name: key
          in: query
          description: Key of the specific metric to retrieve
          required: false
          schema:
            type: string
            example: cpu_usage
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabaseMetrics'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/promote:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: promotePostgresDatabase
      summary: Promote a PostgreSQL read replica (deprecated, use promote-read-replica)
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      deprecated: true
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/promote-read-replica:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: promoteReadReplicaPostgresDatabase
      summary: Promote a PostgreSQL read replica
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/read-replica:
    post:
      operationId: createPostgresDatabaseReadReplica
      summary: Create a read replica of the PostgreSQL database
      parameters:
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/location'
        - $ref: '#/components/parameters/postgres_database_reference'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Name for the read replica
                  type: string
                pg_config:
                  type: object
                  example:
                    max_connections: '100'
                  additionalProperties:
                    type: string
                pgbouncer_config:
                  type: object
                  example:
                    max_client_conn: '100'
                  additionalProperties:
                    type: string
                tags:
                  description: Tags for the read replica
                  type: array
                  items:
                    $ref: '#/components/schemas/PostgresTag'
              additionalProperties: false
              required:
                - name
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/recycle:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: recycle
      summary: Request primary to be recycled
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/rename:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: renamePostgres
      summary: Rename a PostgreSQL database
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: New name for PostgreSQL database
                  type: string
              additionalProperties: false
              required:
                - name
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/reset-superuser-password:
    post:
      operationId: resetSuperuserPassword
      summary: Reset superuser password of the PostgreSQL database
      parameters:
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/location'
        - $ref: '#/components/parameters/postgres_database_reference'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
              additionalProperties: false
              required:
                - password
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/restart:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: restartPostgresDatabase
      summary: Restart a PostgreSQL database
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/restore:
    post:
      operationId: restorePostgresDatabase
      summary: Restore a PostgreSQL database
      parameters:
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/location'
        - $ref: '#/components/parameters/postgres_database_reference'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Name for the newly restored Postgres database.
                  type: string
                restore_target:
                  description: The RFC 3339-formatted timestamp for the point in time at which to recover.
                  type: string
                  format: date-time
                pg_config:
                  type: object
                  example:
                    max_connections: '100'
                  additionalProperties:
                    type: string
                pgbouncer_config:
                  type: object
                  example:
                    max_client_conn: '100'
                  additionalProperties:
                    type: string
                tags:
                  description: Tags for the Postgres Database
                  type: array
                  items:
                    $ref: '#/components/schemas/PostgresTag'
              additionalProperties: false
              required:
                - name
                - restore_target
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/servers:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
    get:
      operationId: listPostgresDatabaseServers
      summary: List servers for a specific PostgreSQL database
      responses:
        '200':
          $ref: '#/components/responses/PostgresServers'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/set-maintenance-window:
    post:
      operationId: setMaintenanceWindow
      summary: Set maintenance window for the PostgreSQL database
      parameters:
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/location'
        - $ref: '#/components/parameters/postgres_database_reference'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                maintenance_window_start_at:
                  type: integer
                maintenance_window_days:
                  type: array
                  items:
                    $ref: '#/components/schemas/MaintenanceWindowDay'
              additionalProperties: false
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/upgrade:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: upgradePostgresDatabase
      summary: Upgrade a PostgreSQL database to the next major version
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabaseUpgradeStatus'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
    get:
      operationId: getPostgresDatabaseUpgradeStatus
      summary: Get PostgreSQL database upgrade status
      parameters:
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/location'
        - $ref: '#/components/parameters/postgres_database_reference'
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabaseUpgradeStatus'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/location/{location}/private-subnet:
    get:
      operationId: listLocationPrivateSubnets
      summary: List private subnets in a location
      parameters:
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/location'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/PrivateSubnets'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Private Subnet
  /project/{project_id}/location/{location}/private-subnet/{private_subnet_reference}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/private_subnet_reference'
    delete:
      operationId: deletePrivateSubnet
      summary: Delete a private subnet
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Private Subnet
    get:
      operationId: getPrivateSubnetDetails
      summary: Get private subnet details
      responses:
        '200':
          $ref: '#/components/responses/PrivateSubnet'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Private Subnet
    post:
      operationId: createPrivateSubnet
      summary: Create a new private subnet
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                firewall_id:
                  type: string
              additionalProperties: false
      responses:
        '200':
          $ref: '#/components/responses/PrivateSubnet'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Private Subnet
  /project/{project_id}/location/{location}/private-subnet/{private_subnet_reference}/connect:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/private_subnet_reference'
    post:
      operationId: connectPrivateSubnet
      summary: Connect private subnet to another private subnet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                connected-subnet-id:
                  type: string
              additionalProperties: false
      responses:
        '200':
          $ref: '#/components/responses/PrivateSubnet'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Private Subnet
  /project/{project_id}/location/{location}/private-subnet/{private_subnet_reference}/disconnect/{private_subnet_id}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/private_subnet_reference'
      - $ref: '#/components/parameters/private_subnet_id'
    post:
      operationId: disconnectPrivateSubnet
      summary: Disconnect private subnet from another private subnet
      responses:
        '200':
          $ref: '#/components/responses/PrivateSubnet'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Private Subnet
  /project/{project_id}/location/{location}/private-subnet/{private_subnet_reference}/rename:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/private_subnet_reference'
    post:
      operationId: renamePrivateSubnet
      summary: Rename a private subnet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: New name for private subnet
                  type: string
              additionalProperties: false
              required:
                - name
      responses:
        '200':
          $ref: '#/components/responses/PrivateSubnet'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Private Subnet
  /project/{project_id}/location/{location}/vm:
    get:
      operationId: listLocationVMs
      summary: List VMs in a location
      parameters:
        - $ref: '#/components/parameters/location'
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/Vms'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Virtual Machine
  /project/{project_id}/location/{location}/vm/{vm_reference}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/vm_reference'
    delete:
      operationId: deleteVM
      summary: Delete a VM
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Virtual Machine
    get:
      operationId: getVMDetails
      summary: Get VM details
      responses:
        '200':
          $ref: '#/components/responses/Vm'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Virtual Machine
    post:
      operationId: createVM
      summary: Create a new VM
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                boot_image:
                  description: Boot image of the VM
                  type: string
                init_script:
                  description: VM init script
                  type: string
                enable_ip4:
                  description: Enable IPv4
                  type: boolean
                private_subnet_id:
                  description: ID of the private subnet
                  type: string
                public_key:
                  description: Public SSH key for the VM, or name of registered SSH public key
                  type: string
                size:
                  description: Size of the VM
                  type: string
                storage_size:
                  description: Requested storage size in GiB
                  type: integer
                gpu:
                  description: Requested GPU count and type, in the form of "count:type"
                  type: string
                unix_user:
                  description: Unix user of the VM
                  type: string
              additionalProperties: false
              required:
                - public_key
      responses:
        '200':
          $ref: '#/components/responses/Vm'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Virtual Machine
  /project/{project_id}/location/{location}/vm/{vm_reference}/rename:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/vm_reference'
    post:
      operationId: renameVM
      summary: Rename a VM
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: New name for VM
                  type: string
              additionalProperties: false
              required:
                - name
      responses:
        '200':
          $ref: '#/components/responses/Vm'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Virtual Machine
  /project/{project_id}/location/{location}/vm/{vm_reference}/restart:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/vm_reference'
    post:
      operationId: restartVM
      summary: Restart a VM
      responses:
        '200':
          $ref: '#/components/responses/Vm'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Virtual Machine
  /project/{project_id}/location/{location}/vm/{vm_reference}/start:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/vm_reference'
    post:
      operationId: startVM
      summary: Start a VM
      responses:
        '200':
          $ref: '#/components/responses/Vm'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Virtual Machine
  /project/{project_id}/location/{location}/vm/{vm_reference}/stop:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/vm_reference'
    post:
      operationId: stopVm
      summary: Stop a VM
      responses:
        '200':
          $ref: '#/components/responses/Vm'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Virtual Machine
  /project/{project_id}/machine-image:
    get:
      operationId: listProjectMachineImages
      summary: List all machine images
      parameters:
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/MachineImages'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Machine Image
  /project/{project_id}/object-info/{object_id}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/object_id'
    get:
      operationId: getObjectInfo
      summary: Return information on object type, location, and name
      responses:
        '200':
          $ref: '#/components/responses/ObjectInfo'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Project
  /project/{project_id}/postgres:
    get:
      operationId: listPostgresDatabases
      summary: List all PostgreSQL databases
      parameters:
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/tags'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabases'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/postgres/capabilities:
    parameters:
      - $ref: '#/components/parameters/project_id'
    get:
      operationId: getPostgresCapabilities
      summary: Get available PostgreSQL provisioning options
      description: Returns a tree of valid option combinations for creating PostgreSQL databases, along with metadata describing each option value. The tree encodes dependency chains (e.g. which VM families are available per location, which storage sizes are valid per VM size).
      responses:
        '200':
          description: PostgreSQL capabilities tree and metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostgresCapabilities'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Postgres Database
  /project/{project_id}/private-location:
    parameters:
      - $ref: '#/components/parameters/project_id'
    get:
      operationId: getPrivateLocations
      summary: List all private locations
      responses:
        '200':
          $ref: '#/components/responses/PrivateLocations'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Private Location
    post:
      operationId: createPrivateLocation
      summary: Create a new private location
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Name of the private location
                  type: string
                provider_location_name:
                  description: Provider location name of the private location
                  type: string
                  enum:
                    - us-west-2
                    - us-east-1
                    - us-east-2
                    - ap-southeast-2
                    - eu-west-1
                access_key:
                  description: Access key for the private location
                  type: string
                secret_key:
                  description: Secret key for the private location
                  type: string
              additionalProperties: false
              required:
                - name
                - provider_location_name
                - access_key
                - secret_key
      responses:
        '200':
          $ref: '#/components/responses/PrivateLocation'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Private Location
  /project/{project_id}/private-location/{private_location_name}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/private_location_name'
    delete:
      operationId: deletePrivateLocation
      summary: Delete a private location
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Private Location
    get:
      operationId: getPrivateLocationDetails
      summary: Get private location details
      responses:
        '200':
          $ref: '#/components/responses/PrivateLocation'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Private Location
    post:
      operationId: updatePrivateLocation
      summary: Update a private location
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Name of the private location
                  type: string
              additionalProperties: false
              required:
                - name
      responses:
        '200':
          $ref: '#/components/responses/PrivateLocation'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Private Location
  /project/{project_id}/private-subnet:
    get:
      operationId: listPSs
      summary: List all private subnets
      parameters:
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/PrivateSubnets'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Private Subnet
  /project/{project_id}/ssh-public-key:
    parameters:
      - $ref: '#/components/parameters/project_id'
    get:
      operationId: getSshPublicKeys
      summary: List all SSH public keys
      responses:
        '200':
          $ref: '#/components/responses/SshPublicKeys'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - SSH Public Key
    post:
      operationId: registerSshPublicKey
      summary: Register a SSH public key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SshPublicKeyCreate'
      responses:
        '200':
          $ref: '#/components/responses/SshPublicKey'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - SSH Public Key
  /project/{project_id}/ssh-public-key/{ssh_public_key_reference}:
    parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/ssh_public_key_reference'
    get:
      operationId: getSshPublicKey
      summary: Get SSH public key details
      responses:
        '200':
          $ref: '#/components/responses/SshPublicKey'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - SSH Public Key
    post:
      operationId: updateSshPublicKey
      summary: Update SSH public key information
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SshPublicKeyUpdate'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SshPublicKey'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - SSH Public Key
    delete:
      operationId: deleteSshPublicKey
      summary: Delete an SSH public key
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - SSH Public Key
  /project/{project_id}/vm:
    get:
      operationId: listProjectVMs
      summary: List all VMs
      parameters:
        - $ref: '#/components/parameters/project_id'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/Vms'
        default:
          $ref: '#/components/responses/Error'
      tags:
        - Virtual Machine
components:
  parameters:
    firewall_reference:
      description: Firewall ID or name
      examples:
        id:
          value: fwn30gjk1d1e2jj34v9x0dq4rp
        name:
          value: firewall-name
      in: path
      name: firewall_reference
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    firewall_rule_id:
      description: ID of the firewall rule
      in: path
      name: firewall_rule_id
      required: true
      schema:
        type: string
        example: fraz0q3vbrpa7pkg7zbmah9csn
        pattern: ^fr[0-9a-hj-km-np-tv-z]{24}$
    github_cache_entry_id:
      description: GitHub cache entry ID
      examples:
        id:
          value: gen30gjk1d1e2jj34v9x0dq4rp
        name:
          value: github-repository-name
      in: path
      name: github_cache_entry_id
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    github_installation_reference:
      description: GitHub installation ID or name
      examples:
        id:
          value: gin30gjk1d1e2jj34v9x0dq4rp
        name:
          value: github-installation-name
      in: path
      name: github_installation_reference
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    github_repository_reference:
      description: GitHub repository ID or name
      examples:
        id:
          value: gpn30gjk1d1e2jj34v9x0dq4rp
        name:
          value: github-repository-name
      in: path
      name: github_repository_reference
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    inference_api_key_id:
      description: ID of the inference API key
      in: path
      name: inference_api_key_id
      required: true
      schema:
        type: string
        example: akkkmx0f2vke4h36nk9cm8v8q0
        pattern: ^ak[0-9a-hj-km-np-tv-z]{24}$
    kubernetes_cluster_reference:
      description: Kubernetes cluster ID or name
      examples:
        id:
          value: kcn30gjk1d1e2jj34v9x0dq4rp
        name:
          value: kubernetes-cluster-name
      in: path
      name: kubernetes_cluster_reference
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    kubernetes_node_name:
      description: Kubernetes node name
      example: kubernetes-node-name
      in: path
      name: kubernetes_node_name
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    kubernetes_nodepool_reference:
      description: Kubernetes nodepool ID or name
      examples:
        id:
          value: kn66ktqjab025mkxhjmavpwjxs
        name:
          value: kubernetes-nodepool-name
      in: path
      name: kubernetes_nodepool_reference
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    load_balancer_reference:
      description: Load balancer ID or name
      examples:
        id:
          value: 1bn30gjk1d1e2jj34v9x0dq4rp
        name:
          value: load-balancer-name
      in: path
      name: load_balancer_reference
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    location:
      description: The Ubicloud location/region
      in: path
      name: location
      required: true
      schema:
        type: string
        example: eu-central-h1
    log_destination_id:
      description: Postgres Log Destination ID
      in: path
      name: log_destination_id
      required: true
      schema:
        type: string
        example: 1d000000000000000000000000
        pattern: ^1d[0-9a-hj-km-np-tv-z]{24}$
    machine_image_new_name:
      description: Name for a new machine image (UBID format not allowed)
      example: my-image
      in: path
      name: machine_image_reference
      required: true
      schema:
        type: string
        pattern: ^(?!m1[0-9a-hj-km-np-tv-z]{24}$)[a-z0-9](?:[a-z0-9\-]{0,61}[a-z0-9])?$
    machine_image_reference:
      description: Machine Image ID or name
      examples:
        id:
          value: m1n30gjk1d1e2jj34v9x0dq4rp
        name:
          value: my-image
      in: path
      name: machine_image_reference
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    machine_image_version:
      description: Version label of the machine image
      example: v1.0
      in: path
      name: version
      required: true
      schema:
        type: string
        pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$
    metric_destination_id:
      description: Postgres Metric Destination ID
      in: path
      name: metric_destination_id
      required: true
      schema:
        type: string
        example: et7ekmf54nae5nya9s6vebg43f
        pattern: ^(et|md)[0-9a-hj-km-np-tv-z]{24}$
    object_id:
      description: ID of a supported object
      in: path
      name: object_id
      required: true
      schema:
        type: string
        example: fwkkmx0f2vke4h36nk9cm8v8q0
        pattern: ^(fw|kc|1b|m1|pg|ps|vm)[0-9a-hj-km-np-tv-z]{24}$
    order_column:
      description: Pagination - Order column
      in: query
      name: order_column
      required: false
      schema:
        type: string
        default: id
    page_size:
      description: Pagination - Page size
      in: query
      name: page_size
      required: false
      schema:
        type: integer
        default: 10
    postgres_database_reference:
      description: Postgres database ID or name
      examples:
        id:
          value: pgn30gjk1d1e2jj34v9x0dq4rp
        name:
          value: postgres-database-name
      in: path
      name: postgres_database_reference
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    private_location_name:
      description: Name of the private location
      in: path
      name: private_location_name
      required: true
      schema:
        type: string
    private_subnet_id:
      description: ID of the private subnet
      in: path
      name: private_subnet_id
      required: true
      schema:
        type: string
        example: pskkmx0f2vke4h36nk9cm8v8q0
        pattern: ^ps[0-9a-hj-km-np-tv-z]{24}$
    private_subnet_reference:
      description: Private subnet ID or name
      examples:
        id:
          value: psn30gjk1d1e2jj34v9x0dq4rp
        name:
          value: private-subnet-name
      in: path
      name: private_subnet_reference
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    project_id:
      description: ID of the project
      in: path
      name: project_id
      required: true
      schema:
        type: string
        example: pjkkmx0f2vke4h36nk9cm8v8q0
        pattern: ^pj[0-9a-hj-km-np-tv-z]{24}$
    ssh_public_key_reference:
      description: SSH public key ID or name
      examples:
        id:
          value: skn30gjk1d1e2jj34v9x0dq4rp
        name:
          value: ssh-public-key-name
      in: path
      name: ssh_public_key_reference
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    start_after:
      description: Pagination - Start after
      in: query
      name: start_after
      required: false
      schema:
        type: string
    tags:
      description: Filter by tags in key:value format (comma-separated for multiple tags)
      in: query
      name: tags
      required: false
      schema:
        type: string
        example: environment:production,team:backend
    vm_reference:
      description: Virtual machine ID or name
      examples:
        id:
          value: vmn30gjk1d1e2jj34v9x0dq4rp
        name:
          value: virtual-machine-name
      in: path
      name: vm_reference
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
  schemas:
    MaintenanceWindowDay:
      type: string
      enum:
        - mon
        - tue
        - wed
        - thu
        - fri
        - sat
        - sun
    Kubeconfig:
      description: Raw YAML content of a Kubernetes cluster configuration file
      type: string
    AuditLog:
      type: object
      properties:
        at:
          description: Timestamp of the action
          type: string
          format: date-time
        action:
          description: Action performed
          type: string
        subject_id:
          description: ID of the account that performed the action
          type: string
        subject_name:
          description: Name of the account that performed the action (if still member of project)
          type: string
        object_ids:
          description: IDs of the objects affected by the action
          type: array
          items:
            type: string
      additionalProperties: false
      required:
        - at
        - action
        - subject_id
        - object_ids
    Error:
      type: object
      properties:
        error:
          type: object
          additionalProperties: false
          properties:
            code:
              type: integer
              example: 401
            message:
              type: string
              example: There was an error logging in
            type:
              type: string
              example: InvalidCredentials
            details:
              type: object
              nullable: true
          required:
            - code
            - message
            - type
      additionalProperties: false
      required:
        - error
    PostgresConfig:
      type: object
      properties:
        pg_config:
          type: object
          example:
            max_connections: '100'
          additionalProperties:
            type: string
        pgbouncer_config:
          type: object
          example:
            max_client_conn: '100'
          additionalProperties:
            type: string
        default_pg_config:
          description: System-computed configuration values based on instance size. User overrides in pg_config take precedence.
          type: object
          additionalProperties:
            type: string
          nullable: true
          readOnly: true
        message:
          description: Informational message about the configuration update, such as restart requirements.
          type: string
          readOnly: true
      additionalProperties: false
      required:
        - pg_config
        - pgbouncer_config
    SshPublicKeyCreate:
      type: object
      properties:
        name:
          type: string
        public_key:
          type: string
      additionalProperties: false
      required:
        - name
        - public_key
    FirewallRuleUpdate:
      anyOf:
        - type: object
          properties:
            cidr:
              description: CIDR of the firewall rule
              type: string
            port_range:
              description: Port range of the firewall rule
              type: string
            protocol:
              description: Protocol of the firewall rule (tcp or udp)
              type: string
            description:
              description: Description of the firewall rule
              type: string
          additionalProperties: false
          required:
            - cidr
        - type: object
          properties:
            port_range:
              description: Port range of the firewall rule
              type: string
            protocol:
              description: Protocol of the firewall rule (tcp or udp)
              type: string
            description:
              description: Description of the firewall rule
              type: string
          additionalProperties: false
          required:
            - port_range
        - type: object
          properties:
            protocol:
              description: Protocol of the firewall rule (tcp or udp)
              type: string
            description:
              description: Description of the firewall rule
              type: string
          additionalProperties: false
          required:
            - protocol
        - type: object
          properties:
            description:
              description: Description of the firewall rule
              type: string
          additionalProperties: false
          required:
            - description
    SshPublicKeyUpdate:
      anyOf:
        - type: object
          properties:
            name:
              type: string
            public_key:
              type: string
          additionalProperties: false
          required:
            - name
        - type: object
          properties:
            public_key:
              type: string
          additionalProperties: false
          required:
            - public_key
    PostgresPatchConfig:
      anyOf:
        - type: object
          properties:
            pg_config:
              type: object
              example:
                max_connections: '100'
              additionalProperties:
                type: string
                nullable: true
            pgbouncer_config:
              type: object
              example:
                max_client_conn: '100'
              additionalProperties:
                type: string
                nullable: true
          additionalProperties: false
          required:
            - pg_config
        - type: object
          properties:
            pgbouncer_config:
              type: object
              example:
                max_client_conn: '100'
              additionalProperties:
                type: string
                nullable: true
          additionalProperties: false
          required:
            - pgbouncer_config
    CertAuthUserRequest:
      type: object
      properties:
        name:
          description: name of user
          type: string
      additionalProperties: false
      required:
        - name
    CertAuthUserList:
      type: object
      properties:
        items:
          type: array
          items:
            type: string
      additionalProperties: false
      required:
        - items
    PostgresTag:
      type: object
      properties:
        key:
          description: Key of the Postgres tag
          type: string
        value:
          description: Value of the Postgres tag
          type: string
      additionalProperties: false
      required:
        - key
        - value
    PrivateLocation:
      type: object
      properties:
        id:
          description: ID of the private location
          type: string
        name:
          description: Name of the private location
          type: string
        ui_name:
          description: UI name of the private location
          type: string
        provider:
          description: Name of the private location
          type: string
        path:
          description: Path of the private location
          type: string
      additionalProperties: false
      required:
        - id
        - name
        - provider
        - path
        - ui_name
    GithubCacheEntry:
      type: object
      properties:
        installation_name:
          description: name of the GitHub installation containing the repository containing the cache entry
          type: string
        repository_name:
          description: name of the GitHub repository containing the cache entry
          type: string
        id:
          description: ID of the GitHub cache entry
          type: string
          example: gefg7td83em22qfw9pq5xyfqb7
          pattern: ^ge[0-9a-hj-km-np-tv-z]{24}$
        key:
          description: GitHub cache entry key
          type: string
        scope:
          description: Branch scope of the GitHub cache entry
          type: string
        size:
          description: Size of the GitHub cache entry in bytes
          type: integer
        created_at:
          description: Timestamp of when the cache entry was created
          type: string
          format: date-time
        last_accessed_at:
          description: Timestamp of when the cache entry was last accessed
          type: string
          format: date-time
          nullable: true
      additionalProperties: false
      required:
        - id
        - installation_name
        - repository_name
        - key
        - scope
        - size
        - created_at
        - last_accessed_at
    GithubRepository:
      type: object
      properties:
        installation_name:
          description: Name of the GitHub installation containing the repository
          type: string
        id:
          description: ID of the GitHub repository
          type: string
          example: gpfg7td83em22qfw9pq5xyfqb7
          pattern: ^gp[0-9a-hj-km-np-tv-z]{24}$
        name:
          description: Name of the GitHub repository
          type: string
      additionalProperties: false
      required:
        - id
        - installation_name
        - name
    GithubInstallation:
      type: object
      properties:
        id:
          description: ID of the GitHub installation
          type: string
          example: g1fg7td83em22qfw9pq5xyfqb7
          pattern: ^g1[0-9a-hj-km-np-tv-z]{24}$
        name:
          description: Name of the GitHub installation (GitHub user/organization name)
          type: string
      additionalProperties: false
      required:
        - id
        - name
    Firewall:
      type: object
      properties:
        description:
          description: Description of the firewall
          type: string
        firewall_rules:
          description: List of firewall rules
          type: array
          items:
            $ref: '#/components/schemas/FirewallRule'
        id:
          description: ID of the firewall
          type: string
          example: fwfg7td83em22qfw9pq5xyfqb7
          pattern: ^fw[0-9a-hj-km-np-tv-z]{24}$
        location:
          description: Location of the firewall
          type: string
        name:
          description: Name of the firewall
          type: string
      additionalProperties: false
      required:
        - description
        - firewall_rules
        - id
        - location
        - name
    FirewallRule:
      type: object
      properties:
        cidr:
          description: CIDR of the firewall rule
          type: string
        id:
          description: ID of the firewall rule
          type: string
          example: fraz0q3vbrpa7pkg7zbmah9csn
          pattern: ^fr[0-9a-hj-km-np-tv-z]{24}$
        port_range:
          description: Port range of the firewall rule
          type: string
        protocol:
          description: Protocol of the firewall rule (tcp or udp)
          type: string
          enum:
            - tcp
            - udp
        description:
          description: Description of the firewall rule
          type: string
      additionalProperties: false
      required:
        - cidr
        - id
        - port_range
        - protocol
        - description
    SshPublicKey:
      type: object
      properties:
        id:
          description: ID of the SSH public key
          type: string
          example: skaz0q3vbrpa7pkg7zbmah9csn
          pattern: ^sk[0-9a-hj-km-np-tv-z]{24}$
        name:
          description: Name of the SSH public key
          type: string
        public_key:
          description: SSH public key data
          type: string
      additionalProperties: false
      required:
        - id
        - name
    InferenceApiKey:
      type: object
      properties:
        id:
          description: ID of the inference API key
          type: string
          example: akaz0q3vbrpa7pkg7zbmah9csn
          pattern: ^ak[0-9a-hj-km-np-tv-z]{24}$
        key:
          description: inference API key data
          type: string
      additionalProperties: false
      required:
        - id
        - key
    InferenceEndpointPrice:
      type: object
      properties:
        per_million_prompt_tokens:
          description: Price per million prompt tokens in USD
          type: number
          nullable: true
        per_million_completion_tokens:
          description: Price per million completion tokens in USD
          type: number
          nullable: true
      additionalProperties: false
      required:
        - per_million_prompt_tokens
        - per_million_completion_tokens
    InferenceEndpoint:
      type: object
      properties:
        id:
          description: ID of the inference endpoint
          type: string
        name:
          description: Name of the model
          type: string
        display_name:
          description: Display name of the model
          type: string
        url:
          description: URL of the inference endpoint
          type: string
        model_name:
          description: Model name of the inference endpoint
          type: string
        tags:
          description: Tags of the inference endpoint
          type: object
        price:
          $ref: '#/components/schemas/InferenceEndpointPrice'
      additionalProperties: false
      required:
        - id
        - name
        - display_name
        - url
        - model_name
        - tags
        - price
    LoadBalancer:
      type: object
      properties:
        algorithm:
          description: Algorithm of the Load Balancer
          type: string
        stack:
          description: Networking stack of the Load Balancer (ipv4, ipv6, or dual)
          type: string
        dst_port:
          description: Destination port for the Load Balancer
          type: integer
        health_check_endpoint:
          description: Health check endpoint URL
          type: string
        health_check_protocol:
          description: Health check endpoint protocol
          type: string
        hostname:
          description: Hostname of the Load Balancer
          type: string
        id:
          description: ID of the Load Balancer
          type: string
          example: 1bhw8r4pn73t1m5f7rn7a5pej2
          pattern: ^1b[0-9a-hj-km-np-tv-z]{24}$
        location:
          description: Location of the Load Balancer
          type: string
        name:
          description: Name of the Load Balancer
          type: string
        src_port:
          description: Source port for the Load Balancer
          type: integer
        cert_enabled:
          description: Whether SSL certificate is enabled
          type: boolean
      additionalProperties: false
      required:
        - algorithm
        - dst_port
        - health_check_endpoint
        - health_check_protocol
        - hostname
        - id
        - name
        - src_port
      x-go-name: LoadBalancerSchema
    MachineImage:
      type: object
      properties:
        id:
          description: ID of the machine image
          type: string
          example: m1n30gjk1d1e2jj34v9x0dq4rp
          pattern: ^m1[0-9a-hj-km-np-tv-z]{24}$
        name:
          description: Name of the machine image
          type: string
          example: my-image
        location:
          description: Location of the machine image
          type: string
          example: eu-central-h1
        arch:
          description: Architecture
          type: string
          enum:
            - x64
            - arm64
        latest_version:
          description: Latest version label
          type: string
          nullable: true
        created_at:
          description: Creation timestamp
          type: string
          format: date-time
      additionalProperties: false
      required:
        - id
        - name
        - location
        - arch
        - created_at
    MachineImageVersion:
      type: object
      properties:
        id:
          description: ID of the machine image version
          type: string
          example: mvn30gjk1d1e2jj34v9x0dq4rp
        version:
          description: Version label
          type: string
          example: v1.0
        state:
          description: Lifecycle state, or null if no metal record exists
          type: string
          enum:
            - creating
            - ready
            - destroying
            - failed
          nullable: true
        actual_size_mib:
          description: Actual size of the image in MiB
          type: integer
          nullable: true
        archive_size_mib:
          description: Size of the archived image in MiB
          type: integer
          nullable: true
        created_at:
          description: Creation timestamp
          type: string
          format: date-time
        latest:
          description: True if this is the machine image's currently-published latest version
          type: boolean
      additionalProperties: false
      required:
        - id
        - version
        - state
        - created_at
        - latest
      x-go-name: MachineImageVersionSchema
    Nic:
      type: object
      properties:
        id:
          description: ID of the NIC
          type: string
        name:
          description: Name of the NIC
          type: string
        private_ipv4:
          description: Private IPv4 address
          type: string
          format: ipv4
        private_ipv6:
          description: Private IPv6 address
          type: string
          format: ipv6
        vm_name:
          description: Name of the VM
          type: string
          nullable: true
      additionalProperties: false
      required:
        - id
        - name
        - private_ipv4
        - private_ipv6
        - vm_name
    PostgresDatabase:
      type: object
      properties:
        flavor:
          description: Kind of Postgres database
          type: string
        ha_type:
          description: High availability type
          type: string
        target_server_count:
          description: Target number of servers (primary + standbys)
          type: integer
        id:
          description: ID of the Postgres database
          type: string
          example: pgn30gjk1d1e2jj34v9x0dq4rp
          pattern: ^pg[0-9a-hj-km-np-tv-z]{24}$
        location:
          description: Location of the Postgres database
          type: string
        name:
          description: Name of the Postgres database
          type: string
        state:
          description: State of the Postgres database
          type: string
        storage_size_gib:
          description: Storage size in GiB
          type: integer
        target_storage_size_gib:
          description: Desired storage size in GiB
          type: integer
        version:
          description: Current Postgres version
          type: string
          enum:
            - '16'
            - '17'
            - '18'
        target_version:
          description: Target Postgres version
          type: string
          enum:
            - '16'
            - '17'
            - '18'
        vm_size:
          description: Size of the underlying VM
          type: string
        target_vm_size:
          description: Desired VM size
          type: string
        ca_certificates:
          description: CA certificates of the root CA used to issue postgres server certificates
          type: string
          nullable: true
        maintenance_window_start_at:
          description: Maintenance window start time
          type: integer
          nullable: true
        maintenance_window_days:
          description: Days of the week the maintenance window applies to (empty list means every day)
          type: array
          items:
            $ref: '#/components/schemas/MaintenanceWindowDay'
        read_replica:
          description: If the database is a read replica or not
          type: boolean
        parent:
          description: Parent Postgres database
          type: string
          nullable: true
        fallback_active:
          description: Whether the primary server is running on a fallback instance type
          type: boolean
        tags:
          description: Tags of the Postgres database
          type: array
          items:
            $ref: '#/components/schemas/PostgresTag'
        created_at:
          description: Creation timestamp of the Postgres database
          type: string
          format: date-time
      additionalProperties: false
      required:
        - flavor
        - ha_type
        - target_server_count
        - id
        - location
        - name
        - state
        - storage_size_gib
        - version
        - target_version
        - vm_size
        - maintenance_window_start_at
        - read_replica
        - fallback_active
        - tags
        - created_at
      x-go-name: PostgresDatabaseSchema
    PostgresDatabaseLogEntry:
      type: object
      properties:
        timestamp:
          description: Log entry timestamp in RFC 3339 format
          type: string
          format: date-time
        stream_name:
          type: string
          enum:
            - postgres
            - pgbouncer
            - upgrade
        severity_level:
          description: Log severity level
          type: string
          enum:
            - DEBUG
            - INFO
            - WARN
            - ERROR
            - FATAL
        message:
          description: Log message body
          type: string
        server_ubid:
          description: UBID of the server that produced this log entry
          type: string
          pattern: ^pv[0-9a-hj-km-np-tv-z]{24}$
        server_role:
          type: string
          enum:
            - primary
            - standby
        context:
          description: Additional context fields parsed from the log entry (e.g. remote_host_port, dbname, pid, user)
          type: object
          additionalProperties:
            type: string
      additionalProperties: false
      required:
        - timestamp
        - stream_name
        - severity_level
        - message
        - server_ubid
        - server_role
    PostgresDatabaseMetrics:
      type: object
      properties:
        metrics:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              key:
                description: Key of the metric
                type: string
                example: cpu_usage
              name:
                description: Name of the metric
                type: string
                example: CPU Usage
              description:
                description: Description of the metric
                type: string
                example: CPU usage of the Postgres database
              unit:
                description: Unit of measurement for the metric
                type: string
                example: percent
                nullable: true
              series:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  properties:
                    labels:
                      description: Labels identifying the time series
                      type: object
                      example:
                        server: pv9z3a26qkyy4qcxrhzg5f1bs8
                      additionalProperties:
                        type: string
                    values:
                      description: Array of timestamp-value pairs
                      type: array
                      items:
                        type: array
                        minItems: 2
                        maxItems: 2
                        items:
                          oneOf:
                            - type: number
                              description: Unix timestamp
                            - type: string
                              description: Sample value
                  required:
                    - labels
                    - values
            required:
              - name
              - unit
              - series
      additionalProperties: false
      required:
        - metrics
    PostgresServer:
      type: object
      properties:
        id:
          description: ID of the server
          type: string
        role:
          description: Role of the server (primary or standby)
          type: string
          enum:
            - primary
            - standby
        state:
          description: Current state of the server
          type: string
          enum:
            - running
            - creating
            - updating
            - unavailable
            - failover
            - restarting
            - synchronizing
            - deleting
        synchronization_status:
          description: Synchronization status of the server
          type: string
          enum:
            - ready
            - catching_up
        vm_size:
          description: Actual VM size of the server
          type: string
        fallback_active:
          description: Whether the server is running on a fallback instance type
          type: boolean
      additionalProperties: false
      required:
        - id
        - role
        - state
        - synchronization_status
    PostgresBackup:
      type: object
      properties:
        key:
          description: Backup key/identifier
          type: string
        last_modified:
          description: Last modified timestamp of the backup
          type: string
          format: date-time
      additionalProperties: false
      required:
        - key
        - last_modified
    PostgresFirewallRule:
      type: object
      properties:
        cidr:
          description: CIDR of the firewall rule
          type: string
        description:
          description: Port information for the firewall rule
          type: string
        id:
          description: ID of the firewall rule
          type: string
          example: frmjgkgbktw62k53005jpx8tt7
          pattern: ^fr[0-9a-hj-km-np-tv-z]{24}$
        port:
          description: Port for the Postgres firewall rule
          type: integer
      additionalProperties: false
      required:
        - cidr
        - id
    PostgresLogDestination:
      type: object
      properties:
        id:
          description: ID of the log destination
          type: string
          example: 1d000000000000000000000000
          pattern: ^1d[0-9a-hj-km-np-tv-z]{24}$
        name:
          description: Name of the log destination
          type: string
        type:
          description: 'Destination type: "otlp" or "syslog"'
          type: string
          enum:
            - otlp
            - syslog
        url:
          description: Destination URL
          type: string
      additionalProperties: false
      required:
        - id
        - name
        - type
        - url
    PrivateSubnet:
      type: object
      properties:
        firewalls:
          type: array
          items:
            $ref: '#/components/schemas/Firewall'
        id:
          description: ID of the subnet
          type: string
          example: ps3dngttwvje2kmr2sn8x12x4r
          pattern: ^ps[0-9a-hj-km-np-tv-z]{24}$
        location:
          description: Location of the subnet
          type: string
        name:
          description: Name of the subnet
          type: string
        net4:
          description: IPv4 CIDR of the subnet
          type: string
        net6:
          description: IPv6 CIDR of the subnet
          type: string
        nics:
          description: List of NICs
          type: array
          items:
            $ref: '#/components/schemas/Nic'
        state:
          description: State of the subnet
          type: string
      additionalProperties: false
      required:
        - firewalls
        - id
        - location
        - name
        - net4
        - net6
        - nics
        - state
    Project:
      type: object
      properties:
        credit:
          description: Remaining credit of the project in $
          type: number
          format: float
          example: 25.4
        discount:
          description: Discount of the project as percentage
          type: integer
          example: 10
        id:
          type: string
          example: pjkkmx0f2vke4h36nk9cm8v8q0
          pattern: ^pj[0-9a-hj-km-np-tv-z]{24}$
        name:
          description: Name of the project
          type: string
          example: my-project
          pattern: ^[a-zA-Z0-9](?:[a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?$
      additionalProperties: false
      required:
        - credit
        - discount
        - id
        - name
    Reference:
      description: Resource ID or name
      type: string
      pattern: ^[a-z0-9](?:[a-z0-9\-]{0,61}[a-z0-9])?$
    Vm:
      type: object
      properties:
        boot_image:
          description: Boot image of the VM
          type: string
        id:
          description: ID of the VM
          type: string
          example: vmhfy8gff8c67hasb0eez2k1pd
          pattern: ^vm[0-9a-hj-km-np-tv-z]{24}$
        ip4:
          description: IPv4 address
          type: string
          format: ipv4
          nullable: true
        ip4_enabled:
          description: Whether IPv4 is enabled
          type: boolean
        ip6:
          description: IPv6 address
          type: string
          format: ipv6
          nullable: true
        location:
          description: Location of the VM
          type: string
          example: eu-central-h1
        name:
          description: Name of the VM
          type: string
          example: my-vm-name
        size:
          description: Size of the underlying VM
          type: string
        state:
          description: State of the VM
          type: string
        storage_size_gib:
          description: Storage size in GiB
          type: integer
        unix_user:
          description: Unix user of the VM
          type: string
      additionalProperties: false
      required:
        - boot_image
        - id
        - ip4
        - ip4_enabled
        - ip6
        - location
        - name
        - size
        - state
        - storage_size_gib
        - unix_user
      x-go-name: VmSchema
    KubernetesCluster:
      type: object
      properties:
        cp_node_count:
          description: Number of control plane nodes
          type: integer
        cp_vms:
          type: array
          items:
            $ref: '#/components/schemas/Vm'
        display_state:
          description: State of the KubernetesCluster
          type: string
        id:
          description: ID of the KubernetesCluster
          type: string
          example: kcqxhqbg86sj0ng5e9ck5n191z
          pattern: ^kc[0-9a-hj-km-np-tv-z]{24}$
        location:
          description: Location of the KubernetesCluster
          type: string
          example: eu-central-h1
        name:
          description: Name of the KubernetesCluster
          type: string
          example: my-cluster-name
        node_size:
          description: Size of each control plane node
          type: string
        nodepools:
          type: array
          items:
            $ref: '#/components/schemas/KubernetesNodepool'
        services_load_balancer_url:
          description: Services
          type: string
          nullable: true
        version:
          description: Version of the KubernetesCluster
          type: string
      additionalProperties: false
      required:
        - cp_node_count
        - id
        - location
        - name
        - node_size
        - version
      x-go-name: KubernetesClusterSchema
    KubernetesNodepool:
      type: object
      properties:
        kubernetes_cluster_id:
          description: Parent KubernetesCluster id
          type: string
          example: kcqxhqbg86sj0ng5e9ck5n191z
          pattern: ^kc[0-9a-hj-km-np-tv-z]{24}$
        id:
          description: ID of the KubernetesNodepool
          type: string
          example: knqxhqbg86sj0ng5e9ck5n191z
          pattern: ^kn[0-9a-hj-km-np-tv-z]{24}$
        name:
          description: Name of the KubernetesNodepool
          type: string
          example: my-nodepool-name
        node_count:
          description: Number of worker nodes
          type: integer
        node_size:
          description: Size of each worker node
          type: string
        version:
          description: Version of the KubernetesNodepool
          type: string
        vms:
          description: Worker VMs definition
          type: array
          items:
            $ref: '#/components/schemas/Vm'
      additionalProperties: false
      required:
        - kubernetes_cluster_id
        - id
        - name
        - node_count
        - node_size
        - version
      x-go-name: KubernetesNodepoolSchema
    PostgresCapabilities:
      description: 'Tree of valid option combinations and metadata for each option value. The option_tree encodes parent-child dependencies: traverse from flavor -> location -> family -> size -> storage_size -> ha_type (with version branching from flavor). Only combinations present in the tree are valid for provisioning.'
      type: object
      properties:
        option_tree:
          description: Nested object where each level maps option values to their valid children.
          type: object
          additionalProperties: true
        metadata:
          description: Display info for option values referenced in the tree
          type: object
          additionalProperties: false
          properties:
            flavor:
              type: object
              additionalProperties:
                type: object
                additionalProperties: false
                properties:
                  display_name:
                    type: string
                required:
                  - display_name
            location:
              type: object
              additionalProperties:
                type: object
                additionalProperties: false
                properties:
                  display_name:
                    type: string
                  ui_name:
                    type: string
                  provider:
                    type: string
                required:
                  - display_name
                  - ui_name
                  - provider
            family:
              type: object
              additionalProperties:
                type: object
                additionalProperties: false
                properties:
                  display_name:
                    type: string
                  category:
                    type: string
                required:
                  - display_name
                  - category
            size:
              type: object
              additionalProperties:
                type: object
                additionalProperties: false
                properties:
                  vcpu:
                    type: integer
                  memory_gib:
                    type: integer
                required:
                  - vcpu
                  - memory_gib
            ha_type:
              type: object
              additionalProperties:
                type: object
                additionalProperties: false
                properties:
                  display_name:
                    type: string
                  standby_count:
                    type: integer
                required:
                  - display_name
                  - standby_count
          required:
            - flavor
            - location
            - family
            - size
            - ha_type
      additionalProperties: false
      required:
        - option_tree
        - metadata
  responses:
    AuditLogs:
      description: A list of audit log entries
      content:
        application/json:
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  $ref: '#/components/schemas/AuditLog'
              pagination_key:
                description: Key to pass to get next page (only present if additional pages)
                type: string
            additionalProperties: false
            required:
              - items
    Delete:
      description: An empty response after successful resource delete
    Error:
      description: An error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PrivateLocation:
      description: A Private Location
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrivateLocation'
    PrivateLocations:
      description: A list of Private Locations
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/PrivateLocation'
            additionalProperties: false
            required:
              - count
              - items
    Firewall:
      description: A Firewall
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Firewall'
    FirewallDetailed:
      description: A Firewall (detailed)
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            allOf:
              - $ref: '#/components/schemas/Firewall'
              - properties:
                  private_subnets:
                    description: List of private subnets
                    type: array
                    items:
                      $ref: '#/components/schemas/PrivateSubnet'
                additionalProperties: false
                required:
                  - private_subnets
    Firewalls:
      description: A list of Firewalls
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Firewall'
            additionalProperties: false
            required:
              - count
              - items
    FirewallRuleOrRules:
      description: A Firewall Rule or array of them
      content:
        application/json:
          schema:
            anyOf:
              - $ref: '#/components/schemas/FirewallRule'
              - type: array
                items:
                  $ref: '#/components/schemas/FirewallRule'
    FirewallRule:
      description: A Firewall Rule
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FirewallRule'
    GithubCacheEntries:
      description: A list of GitHub Cache Entries
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/GithubCacheEntry'
            additionalProperties: false
            required:
              - count
              - items
    GithubCacheEntry:
      description: A GitHub Cache Entry
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GithubCacheEntry'
    GithubRepositories:
      description: A list of GitHub Repositories
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/GithubRepository'
            additionalProperties: false
            required:
              - count
              - items
    GithubRepository:
      description: A GitHub Repository
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GithubRepository'
    GithubInstallation:
      description: A GitHub Installation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GithubInstallation'
    GithubInstallations:
      description: A list of GitHub Installations
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/GithubInstallation'
            additionalProperties: false
            required:
              - count
              - items
    SshPublicKey:
      description: An SSH Public Key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SshPublicKey'
    SshPublicKeys:
      description: A list of Ssh Public Keys
      content:
        application/json:
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  $ref: '#/components/schemas/SshPublicKey'
            additionalProperties: false
            required:
              - items
    InferenceApiKey:
      description: An Inference API Key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InferenceApiKey'
    InferenceApiKeys:
      description: A list of Inference API Keys
      content:
        application/json:
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  $ref: '#/components/schemas/InferenceApiKey'
            additionalProperties: false
            required:
              - items
    InferenceEndpoints:
      description: A list of Inference Endpoints
      content:
        application/json:
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  $ref: '#/components/schemas/InferenceEndpoint'
            additionalProperties: false
            required:
              - items
    LoadBalancer:
      description: A Load Balancer
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            allOf:
              - $ref: '#/components/schemas/LoadBalancer'
              - properties:
                  subnet:
                    description: Subnet of the Load Balancer
                    type: string
                  vms:
                    type: array
                    items:
                      $ref: '#/components/schemas/Vm'
                additionalProperties: false
                required:
                  - location
                  - subnet
                  - vms
    LoadBalancers:
      description: A list of Load Balancers
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/LoadBalancer'
            additionalProperties: false
            required:
              - count
              - items
    ObjectInfo:
      description: Type, location, and name information for object
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                description: Type of object
                type: string
              location:
                description: Location of object
                type: string
              name:
                description: Name of object
                type: string
            additionalProperties: false
            required:
              - type
              - location
              - name
    PostgresDatabase:
      description: A Postgres Database
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            allOf:
              - $ref: '#/components/schemas/PostgresDatabase'
              - additionalProperties: false
                properties:
                  connection_string:
                    description: Connection string to the Postgres database
                    type: string
                    nullable: true
                  private_connection_string:
                    description: Private connection string to the Postgres database, accessible from connected subnets
                    type: string
                    nullable: true
                  username:
                    description: Username for the Postgres database
                    type: string
                    nullable: true
                  password:
                    description: Password for the Postgres database
                    type: string
                    nullable: true
                  hostname:
                    description: Hostname for the Postgres database
                    type: string
                    nullable: true
                  earliest_restore_time:
                    description: Earliest restore time (if primary)
                    type: string
                    nullable: true
                  firewall_rules:
                    description: List of Postgres firewall rules
                    type: array
                    items:
                      $ref: '#/components/schemas/PostgresFirewallRule'
                  latest_restore_time:
                    description: Latest restore time (if primary)"
                    type: string
                  primary:
                    description: Is the database primary
                    type: boolean
                  maintenance_window_start_at:
                    description: Maintenance window start time
                    type: integer
                    nullable: true
                  tags:
                    description: Tags of the Postgres database
                    type: array
                    items:
                      $ref: '#/components/schemas/PostgresTag'
                required:
                  - connection_string
                  - private_connection_string
                  - username
                  - password
                  - hostname
                  - earliest_restore_time
                  - firewall_rules
                  - latest_restore_time
                  - primary
                  - maintenance_window_start_at
                  - tags
    PostgresDatabases:
      description: A list of Postgres Databases
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/PostgresDatabase'
            additionalProperties: false
            required:
              - count
              - items
    PostgresDatabaseUpgradeStatus:
      description: A Postgres Database Upgrade Status
      content:
        application/json:
          schema:
            type: object
            properties:
              current_version:
                type: string
                enum:
                  - '16'
                  - '17'
                  - '18'
              target_version:
                type: string
                enum:
                  - '16'
                  - '17'
                  - '18'
              upgrade_status:
                type: string
              upgrade_stage:
                type: string
                nullable: true
            additionalProperties: false
            required:
              - current_version
              - target_version
              - upgrade_status
    PostgresFirewallRule:
      description: A Postgres Firewall Rule
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PostgresFirewallRule'
    PostgresLogDestination:
      description: A Postgres Log Destination
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PostgresLogDestination'
    PostgresDatabaseLogs:
      description: Log entries for a Postgres Database
      content:
        application/json:
          schema:
            type: object
            properties:
              logs:
                type: array
                items:
                  $ref: '#/components/schemas/PostgresDatabaseLogEntry'
              pagination_key:
                description: Pass as pagination_key to retrieve the next page of results
                type: string
                pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
            additionalProperties: false
            required:
              - logs
    PostgresDatabaseMetrics:
      description: Metrics data for a Postgres Database
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PostgresDatabaseMetrics'
    PostgresFirewallRules:
      description: A list of Postgres Firewall Rules
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/PostgresFirewallRule'
            additionalProperties: false
            required:
              - count
              - items
    PostgresServers:
      description: A list of Postgres Database Servers
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/PostgresServer'
            additionalProperties: false
            required:
              - count
              - items
    PostgresBackups:
      description: A list of Postgres Database Backups
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/PostgresBackup'
            additionalProperties: false
            required:
              - count
              - items
    CertAuthUserList:
      description: full list of users using client certificate authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CertAuthUserList'
    PrivateSubnet:
      description: A Private Subnet
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrivateSubnet'
    PrivateSubnets:
      description: A list of Private Subnets
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/PrivateSubnet'
            additionalProperties: false
            required:
              - count
              - items
    Project:
      description: A Project
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Project'
    Projects:
      description: A list of Projects
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
            additionalProperties: false
            required:
              - count
              - items
    Vm:
      description: A VM
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            allOf:
              - $ref: '#/components/schemas/Vm'
              - additionalProperties: false
                properties:
                  firewalls:
                    description: List of firewalls
                    type: array
                    items:
                      $ref: '#/components/schemas/Firewall'
                  private_ipv4:
                    description: Private IPv4 address
                    type: string
                    format: ipv4
                  private_ipv6:
                    description: Private IPv6 address
                    type: string
                    format: ipv6
                  subnet:
                    description: Subnet of the VM
                    type: string
                  unix_user:
                    description: Unix user of the VM
                    type: string
                  gpu:
                    description: GPU configuration
                    type: string
                required:
                  - firewalls
                  - private_ipv4
                  - private_ipv6
                  - subnet
                  - unix_user
    Vms:
      description: A list of VMs
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Vm'
            additionalProperties: false
            required:
              - count
              - items
    MachineImage:
      description: A machine image
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MachineImage'
    MachineImages:
      description: A list of machine images
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/MachineImage'
            additionalProperties: false
            required:
              - count
              - items
    MachineImageVersion:
      description: A machine image version
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MachineImageVersion'
      x-go-name: MachineImageVersionResponse
    MachineImageVersions:
      description: A list of machine image versions
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/MachineImageVersion'
            additionalProperties: false
            required:
              - count
              - items
    Kubeconfig:
      description: A Kubernetes Cluster configuration file
      content:
        text/yaml:
          schema:
            $ref: '#/components/schemas/Kubeconfig'
    KubernetesCluster:
      description: A KubernetesCluster
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            allOf:
              - $ref: '#/components/schemas/KubernetesCluster'
    KubernetesClusters:
      description: A list of KubernetesClusters
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/KubernetesCluster'
            additionalProperties: false
            required:
              - count
              - items
    KubernetesNodepool:
      description: A Kubernetes node pool
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            allOf:
              - $ref: '#/components/schemas/KubernetesNodepool'
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
tags:
  - description: Firewall Operations
    name: Firewall
  - description: Firewall Rule Operations
    name: Firewall Rule
  - description: Inference API Key Operations
    name: Inference Api Key
  - description: Inference Endpoint Operations
    name: Inference Endpoint
  - description: Load Balancer Operations
    name: Load Balancer
  - description: Login Operations
    name: Login
  - description: Machine Image Operations
    name: Machine Image
  - description: Postgres Database Operations
    name: Postgres Database
  - description: Postgres Firewall Rule Operations
    name: Postgres Firewall Rule
  - description: Postgres Metric Destination
    name: Postgres Metric Destination
  - description: Postgres Log Destination
    name: Postgres Log Destination
  - description: Private Subnet Operations
    name: Private Subnet
  - description: Project Operations
    name: Project
  - description: Virtual Machine Operations
    name: Virtual Machine
  - description: Private Location Operations
    name: Private Location
  - description: Kubernetes Cluster Operations
    name: Kubernetes Cluster
  - description: SSH Public Key Operations
    name: SSH Public Key
  - description: GitHub Operations
    name: GitHub
  - description: Audit Log Operations
    name: Audit Log
security:
  - BearerAuth: []