{
  "swagger": "2.0",
  "info": {
    "title": "Cluster APIs for TiDB Cloud",
    "version": "alpha"
  },
  "tags": [
    {
      "name": "ClusterService"
    }
  ],
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/api/v1/serverless/orgs/{org_id}/projects/{project_id}/clusters/{cluster_id}/advise_indexes": {
      "post": {
        "summary": "Advise indexes on the specified cluster.",
        "operationId": "AdviseIndexes",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/ClusterAdviseIndexesResp"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "org_id",
            "description": "The ID of the org.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "project_id",
            "description": "The ID of the project.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "cluster_id",
            "description": "The ID of the cluster.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "payload",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ClusterAdviseIndexesReq.Payload"
            }
          },
          {
            "name": "with_cloud_admin",
            "in": "query",
            "required": false,
            "type": "boolean"
          }
        ],
        "tags": [
          "ClusterService"
        ]
      }
    },
    "/api/v1/serverless/orgs/{org_id}/projects/{project_id}/clusters/{cluster_id}/apply_advice": {
      "post": {
        "summary": "Apply an index advisor record.",
        "operationId": "ApplyAdvice",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/ApplyIndexAdviceResp"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "org_id",
            "description": "The ID of the org.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "project_id",
            "description": "The ID of the project.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "cluster_id",
            "description": "The ID of the cluster.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "payload",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ApplyIndexAdviceReq.Payload"
            }
          },
          {
            "name": "with_cloud_admin",
            "in": "query",
            "required": false,
            "type": "boolean"
          }
        ],
        "tags": [
          "ClusterService"
        ]
      }
    },
    "/api/v1/serverless/orgs/{org_id}/projects/{project_id}/clusters/{cluster_id}/close_advice": {
      "post": {
        "summary": "Close an index advisor record.",
        "operationId": "CloseAdvice",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/CloseIndexAdviceResp"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "org_id",
            "description": "The ID of the org.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "project_id",
            "description": "The ID of the project.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "cluster_id",
            "description": "The ID of the cluster.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "payload",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/CloseIndexAdviceReq.Payload"
            }
          },
          {
            "name": "with_cloud_admin",
            "in": "query",
            "required": false,
            "type": "boolean"
          }
        ],
        "tags": [
          "ClusterService"
        ]
      }
    },
    "/api/v1/serverless/orgs/{org_id}/projects/{project_id}/clusters/{cluster_id}/databases": {
      "get": {
        "summary": "List databases of a cluster.",
        "operationId": "ListClusterDatabases",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/ClusterListDatabasesResp"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "org_id",
            "description": "The ID of the org.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "project_id",
            "description": "The ID of the project.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "cluster_id",
            "description": "The ID of the cluster.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          }
        ],
        "tags": [
          "ClusterService"
        ]
      },
      "post": {
        "summary": "Create a database of a cluster.",
        "operationId": "CreateClusterDatabase",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/ClusterCreateDatabaseResp"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "org_id",
            "description": "The ID of the org.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "project_id",
            "description": "The ID of the project.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "cluster_id",
            "description": "The ID of the cluster.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "payload",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ClusterCreateDatabaseReq.Payload"
            }
          }
        ],
        "tags": [
          "ClusterService"
        ]
      }
    },
    "/api/v1/serverless/orgs/{org_id}/projects/{project_id}/clusters/{cluster_id}/features:check": {
      "get": {
        "operationId": "ClusterService_CheckFeature",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/CheckFeatureResp"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "org_id",
            "description": "The organize ID",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "project_id",
            "description": "The project ID",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "cluster_id",
            "description": "The ID of the cluster.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "feature_name",
            "description": "The feature name",
            "in": "query",
            "required": true,
            "type": "string",
            "enum": [
              "CHANGEFEED",
              "PRIVATE_LINK_CONNECTION",
              "DATABASE_AUDIT_LOG"
            ]
          }
        ],
        "tags": [
          "ClusterService"
        ]
      }
    },
    "/api/v1/serverless/orgs/{org_id}/projects/{project_id}/clusters/{cluster_id}/index_advices": {
      "get": {
        "summary": "List index advisor results of a cluster.",
        "operationId": "ListIndexAdvices",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/ListIndexAdvicesResp"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "org_id",
            "description": "The ID of the org.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "project_id",
            "description": "The ID of the project.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "cluster_id",
            "description": "The ID of the cluster.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "page_token",
            "description": "The number of pages.",
            "in": "query",
            "required": false,
            "type": "integer",
            "format": "int64",
            "default": 1
          },
          {
            "name": "page_size",
            "description": "The size of a page.",
            "in": "query",
            "required": false,
            "type": "integer",
            "format": "int64",
            "default": 10
          },
          {
            "name": "state_filter",
            "description": "The state to filter result.",
            "in": "query",
            "required": false,
            "type": "string",
            "enum": [
              "OPEN",
              "APPLYING",
              "APPLIED",
              "CLOSED"
            ]
          },
          {
            "name": "name_filter",
            "description": "The name of database or table to filter result.",
            "in": "query",
            "required": false,
            "type": "string"
          },
          {
            "name": "order_by",
            "description": "The column used to order result.",
            "in": "query",
            "required": false,
            "type": "string"
          },
          {
            "name": "desc",
            "description": "If ordered result should be in descending order.",
            "in": "query",
            "required": false,
            "type": "boolean",
            "default": "false"
          }
        ],
        "tags": [
          "ClusterService"
        ]
      }
    },
    "/api/v1/serverless/orgs/{org_id}/projects/{project_id}/clusters/{cluster_id}/index_advices/{advice_id}": {
      "get": {
        "summary": "Get detail of a index advice.",
        "operationId": "GetIndexAdvice",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/GetIndexAdviceResp"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "org_id",
            "description": "The ID of the org.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "project_id",
            "description": "The ID of the project.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "cluster_id",
            "description": "The ID of the cluster.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "advice_id",
            "description": "The ID of the advice.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          }
        ],
        "tags": [
          "ClusterService"
        ]
      }
    },
    "/api/v1/serverless/orgs/{org_id}/projects/{project_id}/clusters/{cluster_id}/index_advices_summary": {
      "get": {
        "summary": "Get summary of open index advices.",
        "operationId": "GetIndexAdviceSummary",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/GetIndexAdviceSummaryResp"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "org_id",
            "description": "The ID of the org.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "project_id",
            "description": "The ID of the project.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "cluster_id",
            "description": "The ID of the cluster.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          }
        ],
        "tags": [
          "ClusterService"
        ]
      }
    }
  },
  "definitions": {
    "Any": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "string"
        }
      },
      "additionalProperties": {}
    },
    "ApplyIndexAdviceReq.Payload": {
      "type": "object",
      "properties": {
        "advice_id": {
          "type": "string",
          "format": "uint64",
          "example": 1,
          "description": "The ID of the advice record."
        }
      },
      "required": [
        "advice_id"
      ]
    },
    "ApplyIndexAdviceResp": {
      "type": "object",
      "properties": {
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      },
      "required": [
        "base_resp"
      ]
    },
    "BaseResp": {
      "type": "object",
      "properties": {
        "tags": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "title": "such as: request_id, trace_id"
        },
        "err_code": {
          "type": "string",
          "format": "int64"
        },
        "err_msg": {
          "type": "string"
        }
      }
    },
    "CheckFeatureResp": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      }
    },
    "CloseIndexAdviceReq.Payload": {
      "type": "object",
      "properties": {
        "advice_id": {
          "type": "string",
          "format": "uint64",
          "example": 1,
          "description": "The ID of the advice record."
        }
      },
      "required": [
        "advice_id"
      ]
    },
    "CloseIndexAdviceResp": {
      "type": "object",
      "properties": {
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      },
      "required": [
        "base_resp"
      ]
    },
    "ClusterAdviseIndexesReq.Payload": {
      "type": "object",
      "properties": {
        "database_name": {
          "type": "string",
          "example": "helloworld",
          "description": "The name of the database."
        },
        "queries": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Queries"
        }
      },
      "required": [
        "database_name",
        "queries"
      ]
    },
    "ClusterAdviseIndexesResp": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "description": "The items of databases in the cluster."
        },
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      },
      "required": [
        "text",
        "base_resp"
      ]
    },
    "ClusterCreateDatabaseReq.Payload": {
      "type": "object",
      "properties": {
        "database_name": {
          "type": "string",
          "example": "helloworld",
          "description": "The name of the database."
        }
      },
      "required": [
        "database_name"
      ]
    },
    "ClusterCreateDatabaseResp": {
      "type": "object",
      "properties": {
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      },
      "required": [
        "base_resp"
      ]
    },
    "ClusterListDatabasesResp": {
      "type": "object",
      "properties": {
        "databases": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The items of databases in the cluster."
        },
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      },
      "required": [
        "databases",
        "base_resp"
      ]
    },
    "FeatureName.Enum": {
      "type": "string",
      "enum": [
        "CHANGEFEED",
        "PRIVATE_LINK_CONNECTION",
        "DATABASE_AUDIT_LOG"
      ]
    },
    "GetIndexAdviceResp": {
      "type": "object",
      "properties": {
        "advice": {
          "$ref": "#/definitions/IndexAdvice"
        },
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      }
    },
    "GetIndexAdviceSummaryResp": {
      "type": "object",
      "properties": {
        "open_count": {
          "type": "integer",
          "format": "int64"
        },
        "improvement": {
          "type": "number",
          "format": "double"
        },
        "cost_saving_monthly": {
          "type": "number",
          "format": "double"
        },
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      }
    },
    "IndexAdvice": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uint64"
        },
        "name": {
          "type": "string"
        },
        "database": {
          "type": "string"
        },
        "table": {
          "type": "string"
        },
        "last_recommend_time": {
          "type": "string",
          "format": "date-time"
        },
        "state": {
          "$ref": "#/definitions/IndexAdviceState"
        },
        "index_statement": {
          "type": "string"
        },
        "improvement": {
          "type": "number",
          "format": "double"
        },
        "index_size": {
          "type": "number",
          "format": "double"
        },
        "reason": {
          "type": "string"
        },
        "top_impacted_queries": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/IndexAdviceImpact"
          }
        },
        "state_reason": {
          "type": "string"
        },
        "cost_saving_monthly": {
          "type": "number",
          "format": "double"
        },
        "cost_saving_per_query": {
          "type": "number",
          "format": "double"
        }
      }
    },
    "IndexAdviceImpact": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string"
        },
        "improvement": {
          "type": "number",
          "format": "double"
        }
      }
    },
    "IndexAdviceState": {
      "type": "string",
      "enum": [
        "OPEN",
        "APPLYING",
        "APPLIED",
        "CLOSED"
      ]
    },
    "ListIndexAdvicesResp": {
      "type": "object",
      "properties": {
        "advices": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/IndexAdvice"
          },
          "description": "The items of index advisor results."
        },
        "total": {
          "type": "integer",
          "format": "int64",
          "description": "total items count considering filter"
        },
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      },
      "required": [
        "advices",
        "base_resp"
      ]
    },
    "Status": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/Any"
          }
        }
      }
    }
  },
  "securityDefinitions": {
    "bearer": {
      "type": "apiKey",
      "description": "Authentication token, prefixed by Bearer: 'Bearer token'",
      "name": "Authorization",
      "in": "header"
    }
  }
}