{
  "swagger": "2.0",
  "info": {
    "title": "TiDB Cloud Serverless Open API",
    "description": "TiDB Cloud Serverless Open API",
    "version": "v1beta1"
  },
  "tags": [
    {
      "name": "ServerlessService"
    }
  ],
  "host": "serverless.tidbapi.com",
  "basePath": "/serverless/api/v1beta1",
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/serverless/api/v1beta1/clusters": {
      "get": {
        "summary": "Provides a list of TiDB Serverless clusters in a project.",
        "operationId": "ServerlessService_ListClusters",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1ListClustersResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "pageSize",
            "description": "Optional. The maximum number of clusters to return.",
            "in": "query",
            "required": false,
            "type": "integer",
            "format": "int32"
          },
          {
            "name": "pageToken",
            "description": "Optional. The page token from the previous response for pagination.",
            "in": "query",
            "required": false,
            "type": "string"
          },
          {
            "name": "filter",
            "description": "Optional. The filter expression to filter clusters.",
            "in": "query",
            "required": false,
            "type": "string"
          },
          {
            "name": "orderBy",
            "description": "Optional. The order by expression for sorting clusters.",
            "in": "query",
            "required": false,
            "type": "string"
          },
          {
            "name": "orgId",
            "description": "Organization id",
            "in": "query",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "projectId",
            "description": "Project id",
            "in": "query",
            "required": true,
            "type": "string",
            "format": "uint64"
          }
        ],
        "tags": [
          "ServerlessService"
        ]
      },
      "post": {
        "summary": "Creates a new TiDB Serverless cluster.",
        "operationId": "ServerlessService_CreateCluster",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1Cluster"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "cluster",
            "description": "Required. The cluster to be created.",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1Cluster"
            }
          },
          {
            "name": "orgId",
            "description": "Organization id",
            "in": "query",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "projectId",
            "description": "Project id",
            "in": "query",
            "required": true,
            "type": "string",
            "format": "uint64"
          }
        ],
        "tags": [
          "ServerlessService"
        ]
      }
    },
    "/serverless/api/v1beta1/clusters/{clusterId}": {
      "delete": {
        "summary": "Deletes a specific TiDB Serverless cluster.",
        "operationId": "ServerlessService_DeleteCluster",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1Cluster"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "Required. The ID of the cluster to be deleted.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "orgId",
            "description": "Organization id",
            "in": "query",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "projectId",
            "description": "Project id",
            "in": "query",
            "required": true,
            "type": "string",
            "format": "uint64"
          }
        ],
        "tags": [
          "ServerlessService"
        ]
      },
      "get": {
        "summary": "Retrieves details of a specific TiDB Serverless cluster.",
        "operationId": "ServerlessService_GetCluster",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1Cluster"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "Required. The ID of the cluster to be retrieved.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "view",
            "description": "Optional. The level of detail to return for the cluster.\n\n - CLUSTER_VIEW_UNSPECIFIED: The server default is used if unspecified.\n - BASIC: Only basic information about the cluster is returned.\n - FULL: All details about the cluster are returned.",
            "in": "query",
            "required": false,
            "type": "string",
            "enum": [
              "CLUSTER_VIEW_UNSPECIFIED",
              "BASIC",
              "FULL"
            ],
            "default": "CLUSTER_VIEW_UNSPECIFIED"
          },
          {
            "name": "orgId",
            "description": "Organization id",
            "in": "query",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "projectId",
            "description": "Project id",
            "in": "query",
            "required": true,
            "type": "string",
            "format": "uint64"
          }
        ],
        "tags": [
          "ServerlessService"
        ]
      },
      "patch": {
        "summary": "Partially updates a specific TiDB Serverless cluster.",
        "operationId": "ServerlessService_PartialUpdateCluster",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1Cluster"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "Output_only. The unique ID of the cluster.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "properties": {
                "cluster": {
                  "description": "Required. The cluster to be updated.",
                  "properties": {
                    "annotations": {
                      "additionalProperties": {
                        "type": "string"
                      },
                      "description": "Optional. The annotations for the cluster.\ntidb.cloud/has-set-password. The annotation for whether the cluster has set password.\ntidb.cloud/available-features. The annotation for the available features of the cluster.",
                      "type": "object"
                    },
                    "automatedBackupPolicy": {
                      "$ref": "#/definitions/v1beta1ClusterAutomatedBackupPolicy",
                      "description": "Optional. Automated backup policy to set on the cluster."
                    },
                    "createTime": {
                      "description": "Output_only. Timestamp when the cluster was created.",
                      "format": "date-time",
                      "readOnly": true,
                      "type": "string"
                    },
                    "createdBy": {
                      "description": "Output_only. The email of the creator of the cluster.",
                      "readOnly": true,
                      "type": "string"
                    },
                    "displayName": {
                      "description": "Required. User friendly display name of the cluster.",
                      "type": "string"
                    },
                    "encryptionConfig": {
                      "$ref": "#/definitions/v1beta1ClusterEncryptionConfig",
                      "description": "Optional. Encryption settings for the cluster."
                    },
                    "endpoints": {
                      "$ref": "#/definitions/v1beta1ClusterEndpoints",
                      "description": "Optional. The endpoints for connecting to the cluster."
                    },
                    "labels": {
                      "additionalProperties": {
                        "type": "string"
                      },
                      "description": "Optional. The labels for the cluster.\ntidb.cloud/organization. The label for the cluster organization id.\ntidb.cloud/project. The label for the cluster project id.",
                      "type": "object"
                    },
                    "name": {
                      "description": "Output_only. The unique name of the cluster.",
                      "readOnly": true,
                      "type": "string"
                    },
                    "region": {
                      "$ref": "#/definitions/commonv1beta1Region",
                      "description": "Required. Region where the cluster will be created."
                    },
                    "spendingLimit": {
                      "$ref": "#/definitions/ClusterSpendingLimit",
                      "description": "Optional. The spending limit for the cluster."
                    },
                    "state": {
                      "$ref": "#/definitions/commonv1beta1ClusterState",
                      "description": "Output_only. The current state of the cluster.",
                      "readOnly": true
                    },
                    "updateTime": {
                      "description": "Output_only. Timestamp when the cluster was last updated.",
                      "format": "date-time",
                      "readOnly": true,
                      "type": "string"
                    },
                    "usage": {
                      "$ref": "#/definitions/v1beta1ClusterUsage",
                      "description": "Output_only. Usage details of the cluster.",
                      "readOnly": true
                    },
                    "userPrefix": {
                      "description": "Output_only. The unique prefix in SQL user name.",
                      "readOnly": true,
                      "type": "string"
                    },
                    "version": {
                      "description": "Output_only. The TiDB version of the cluster.",
                      "readOnly": true,
                      "type": "string"
                    }
                  },
                  "title": "Required. The cluster to be updated.",
                  "type": "object"
                },
                "updateMask": {
                  "description": "Required. The update mask indicating which fields are to be updated.",
                  "type": "string"
                }
              },
              "description": "Message for requesting a partial update on a TiDB Serverless cluster."
            }
          },
          {
            "name": "orgId",
            "description": "Organization id",
            "in": "query",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "projectId",
            "description": "Project id",
            "in": "query",
            "required": true,
            "type": "string",
            "format": "uint64"
          }
        ],
        "tags": [
          "ServerlessService"
        ]
      }
    },
    "/serverless/api/v1beta1/clusters/{clusterId}/password": {
      "put": {
        "summary": "Changes the root password of a specific TiDB Serverless cluster.",
        "operationId": "ServerlessService_ChangeRootPassword",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1beta1ChangeRootPasswordResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "Required. The ID of the cluster for which the password is to be changed.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "properties": {
                "password": {
                  "description": "Required. The new root password for the cluster.",
                  "type": "string"
                }
              },
              "description": "Message for requesting to change the root password of a TiDB Serverless cluster."
            }
          },
          {
            "name": "orgId",
            "description": "Organization id",
            "in": "query",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "projectId",
            "description": "Project id",
            "in": "query",
            "required": true,
            "type": "string",
            "format": "uint64"
          }
        ],
        "tags": [
          "ServerlessService"
        ]
      }
    },
    "/serverless/api/v1beta1/regions": {
      "get": {
        "summary": "Provides a list of available regions for TiDB Serverless clusters.",
        "operationId": "ServerlessService_ListRegions",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1ListRegionsResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "orgId",
            "description": "Organization id",
            "in": "query",
            "required": true,
            "type": "string",
            "format": "uint64"
          }
        ],
        "tags": [
          "ServerlessService"
        ]
      }
    }
  },
  "definitions": {
    "ClusterSpendingLimit": {
      "description": "Message for spending limit configuration.",
      "properties": {
        "monthly": {
          "description": "Optional. Maximum monthly spending limit in USD cents.",
          "format": "int32",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "EndpointsPrivate": {
      "description": "Message for private endpoint to securely connect to the cluster.",
      "properties": {
        "aws": {
          "$ref": "#/definitions/PrivateAWS",
          "readOnly": true
        },
        "gcp": {
          "$ref": "#/definitions/PrivateGCP",
          "readOnly": true
        },
        "host": {
          "description": "Output_only. The hostname of the private endpoint.",
          "readOnly": true,
          "type": "string"
        },
        "port": {
          "description": "Output_only. The port of the private endpoint.",
          "format": "int32",
          "readOnly": true,
          "type": "integer"
        }
      },
      "type": "object"
    },
    "EndpointsPublic": {
      "description": "Message for public endpoint to connect to the cluster.",
      "properties": {
        "disabled": {
          "description": "Optional. Whether the public endpoint is disabled.",
          "type": "boolean"
        },
        "host": {
          "description": "Output_only. The hostname of the public endpoint.",
          "readOnly": true,
          "type": "string"
        },
        "port": {
          "description": "Output_only. The port of the public endpoint.",
          "format": "int32",
          "readOnly": true,
          "type": "integer"
        }
      },
      "type": "object"
    },
    "PrivateAWS": {
      "description": "Message for AWS PrivateLink information.",
      "properties": {
        "availabilityZone": {
          "description": "Output_only. The availability zones that the service is available in.",
          "items": {
            "type": "string"
          },
          "readOnly": true,
          "type": "array"
        },
        "serviceName": {
          "description": "Output_only. The AWS service name for private access.",
          "readOnly": true,
          "type": "string"
        }
      },
      "type": "object"
    },
    "PrivateGCP": {
      "description": "Message for GCP Private Service information.",
      "properties": {
        "serviceAttachmentName": {
          "description": "Output_only. The target GCP service attachment name for private access.",
          "readOnly": true,
          "type": "string"
        }
      },
      "type": "object"
    },
    "commonv1beta1ClusterState": {
      "default": "CLUSTER_STATE_UNSPECIFIED",
      "description": "Enum for current state of a cluster.\n\n - CREATING: Cluster is being created.\n - DELETING: Cluster is being deleted.\n - ACTIVE: Cluster is active for use.\n - RESTORING: Cluster data is being restored.\n - MAINTENANCE: Cluster is under maintenance.\n - DELETED: Cluster has been deleted.\n - INACTIVE: Cluster is not active, but not being deleted.\n - UPDATING: Cluster is being updated.\nOnly for Dedicated Cluster.\n - IMPORTING: Cluster is being imported.\nOnly for Dedicated Cluster.\n - MODIFYING: Cluster is being modified.\nOnly for Dedicated Cluster.\n - PAUSING: Cluster is being paused.\nOnly for Dedicated Cluster.\n - PAUSED: Cluster is paused.\nOnly for Dedicated Cluster.\n - RESUMING: Cluster is resuming.\nOnly for Dedicated Cluster.\n - SCALING: Cluster is scaling.\nOnly for Dedicated Cluster.\nOnly for Mgmt Internal API.",
      "enum": [
        "CLUSTER_STATE_UNSPECIFIED",
        "CREATING",
        "DELETING",
        "ACTIVE",
        "RESTORING",
        "MAINTENANCE",
        "DELETED",
        "INACTIVE",
        "UPDATING",
        "IMPORTING",
        "MODIFYING",
        "PAUSING",
        "PAUSED",
        "RESUMING",
        "SCALING"
      ],
      "type": "string"
    },
    "commonv1beta1Region": {
      "description": "Message for describing a region for deploying TiDB Serverless clusters.",
      "properties": {
        "displayName": {
          "description": "Output only. User-friendly display name of the region.",
          "readOnly": true,
          "type": "string"
        },
        "id": {
          "example": "us-west-2",
          "readOnly": true,
          "type": "string"
        },
        "name": {
          "description": "Required. The unique name of the region.",
          "example": "regions/aws-us-west-2",
          "pattern": "^regions/(aws|gcp|azure)-(.+)$",
          "type": "string"
        },
        "provider": {
          "$ref": "#/definitions/v1beta1RegionCloudProvider",
          "description": "Output only. The cloud provider for the region.",
          "readOnly": true
        }
      },
      "required": [
        "name"
      ],
      "type": "object"
    },
    "googlerpcStatus": {
      "properties": {
        "code": {
          "format": "int32",
          "type": "integer"
        },
        "details": {
          "items": {
            "$ref": "#/definitions/protobufAny",
            "type": "object"
          },
          "type": "array"
        },
        "message": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "protobufAny": {
      "additionalProperties": {},
      "properties": {
        "@type": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "serverlessv1beta1ClusterView": {
      "default": "CLUSTER_VIEW_UNSPECIFIED",
      "description": "Enum for the different types of detail view to be returned for a TiDB Serverless cluster.\n\n - CLUSTER_VIEW_UNSPECIFIED: The server default is used if unspecified.\n - BASIC: Only basic information about the cluster is returned.\n - FULL: All details about the cluster are returned.",
      "enum": [
        "CLUSTER_VIEW_UNSPECIFIED",
        "BASIC",
        "FULL"
      ],
      "type": "string"
    },
    "tidb_cloud_open_apiserverlessv1beta1Cluster": {
      "description": "Message for a serverless TiDB cluster resource.",
      "properties": {
        "annotations": {
          "additionalProperties": {
            "type": "string"
          },
          "description": "Optional. The annotations for the cluster.\ntidb.cloud/has-set-password. The annotation for whether the cluster has set password.\ntidb.cloud/available-features. The annotation for the available features of the cluster.",
          "type": "object"
        },
        "automatedBackupPolicy": {
          "$ref": "#/definitions/v1beta1ClusterAutomatedBackupPolicy",
          "description": "Optional. Automated backup policy to set on the cluster."
        },
        "clusterId": {
          "description": "Output_only. The unique ID of the cluster.",
          "readOnly": true,
          "type": "string"
        },
        "createTime": {
          "description": "Output_only. Timestamp when the cluster was created.",
          "format": "date-time",
          "readOnly": true,
          "type": "string"
        },
        "createdBy": {
          "description": "Output_only. The email of the creator of the cluster.",
          "readOnly": true,
          "type": "string"
        },
        "displayName": {
          "description": "Required. User friendly display name of the cluster.",
          "type": "string"
        },
        "encryptionConfig": {
          "$ref": "#/definitions/v1beta1ClusterEncryptionConfig",
          "description": "Optional. Encryption settings for the cluster."
        },
        "endpoints": {
          "$ref": "#/definitions/v1beta1ClusterEndpoints",
          "description": "Optional. The endpoints for connecting to the cluster."
        },
        "labels": {
          "additionalProperties": {
            "type": "string"
          },
          "description": "Optional. The labels for the cluster.\ntidb.cloud/organization. The label for the cluster organization id.\ntidb.cloud/project. The label for the cluster project id.",
          "type": "object"
        },
        "name": {
          "description": "Output_only. The unique name of the cluster.",
          "readOnly": true,
          "type": "string"
        },
        "region": {
          "$ref": "#/definitions/commonv1beta1Region",
          "description": "Required. Region where the cluster will be created."
        },
        "spendingLimit": {
          "$ref": "#/definitions/ClusterSpendingLimit",
          "description": "Optional. The spending limit for the cluster."
        },
        "state": {
          "$ref": "#/definitions/commonv1beta1ClusterState",
          "description": "Output_only. The current state of the cluster.",
          "readOnly": true
        },
        "updateTime": {
          "description": "Output_only. Timestamp when the cluster was last updated.",
          "format": "date-time",
          "readOnly": true,
          "type": "string"
        },
        "usage": {
          "$ref": "#/definitions/v1beta1ClusterUsage",
          "description": "Output_only. Usage details of the cluster.",
          "readOnly": true
        },
        "userPrefix": {
          "description": "Output_only. The unique prefix in SQL user name.",
          "readOnly": true,
          "type": "string"
        },
        "version": {
          "description": "Output_only. The TiDB version of the cluster.",
          "readOnly": true,
          "type": "string"
        }
      },
      "required": [
        "displayName",
        "region"
      ],
      "type": "object"
    },
    "tidb_cloud_open_apiserverlessv1beta1ListClustersResponse": {
      "description": "Responses message to the request for listing of TiDB Serverless clusters.",
      "properties": {
        "clusters": {
          "description": "A list of clusters.",
          "items": {
            "$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1Cluster",
            "type": "object"
          },
          "type": "array"
        },
        "nextPageToken": {
          "description": "Token provided to retrieve the next page of results.",
          "type": "string"
        },
        "totalSize": {
          "description": "Total number of available clusters.",
          "format": "int64",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "tidb_cloud_open_apiserverlessv1beta1ListRegionsResponse": {
      "description": "Responses message to the request for listing of available regions in TiDB Serverless.",
      "properties": {
        "regions": {
          "description": "A list of available regions.",
          "items": {
            "$ref": "#/definitions/commonv1beta1Region",
            "type": "object"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "v1beta1ChangeRootPasswordResponse": {
      "description": "Responses message to the request for changing the root password of a TiDB Serverless cluster.",
      "type": "object"
    },
    "v1beta1ClusterAutomatedBackupPolicy": {
      "description": "Message for automated backup configuration for a cluster.",
      "properties": {
        "retentionDays": {
          "description": "Optional. Number of days to retain automated backups.",
          "format": "int32",
          "type": "integer"
        },
        "startTime": {
          "description": "Optional. Cron expression for when automated backups should start.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "v1beta1ClusterEncryptionConfig": {
      "description": "Message for encryption settings for a cluster.",
      "properties": {
        "enhancedEncryptionEnabled": {
          "description": "Optional. Whether enhanced encryption for cluster data is enabled.",
          "type": "boolean"
        }
      },
      "type": "object"
    },
    "v1beta1ClusterEndpoints": {
      "description": "Message for endpoint information for connecting to a cluster.",
      "properties": {
        "private": {
          "$ref": "#/definitions/EndpointsPrivate",
          "description": "Output_only. Private endpoint to securely connect to the cluster.",
          "readOnly": true
        },
        "public": {
          "$ref": "#/definitions/EndpointsPublic",
          "description": "Optional. Public endpoint to connect to the cluster."
        }
      },
      "type": "object"
    },
    "v1beta1ClusterUsage": {
      "description": "Message for usage statistics of a cluster.",
      "properties": {
        "columnarStorage": {
          "description": "Output_only. The storage used on column-based storage in bytes.",
          "format": "double",
          "readOnly": true,
          "type": "number"
        },
        "requestUnit": {
          "description": "Output_only. The Request Units used in this month.",
          "format": "int64",
          "readOnly": true,
          "type": "string"
        },
        "rowBasedStorage": {
          "description": "Output_only. The storage used on row-based storage in bytes.",
          "format": "double",
          "readOnly": true,
          "type": "number"
        }
      },
      "type": "object"
    },
    "v1beta1RegionCloudProvider": {
      "default": "CLOUD_PROVIDER_UNSPECIFIED",
      "description": "- CLOUD_PROVIDER_UNSPECIFIED: Unspecified cloud provider.\n - AWS: Amazon Web Services.\n - GCP: Google Cloud Platform.\n - AZURE: Microsoft Azure.",
      "enum": [
        "CLOUD_PROVIDER_UNSPECIFIED",
        "AWS",
        "GCP",
        "AZURE"
      ],
      "title": "Enum for cloud providers for the region.\n@gotags: tag:\"replace\"",
      "type": "string"
    }
  }
}