{
  "swagger": "2.0",
  "info": {
    "title": "Branch APIs for TiDB Cloud",
    "version": "alpha"
  },
  "tags": [
    {
      "name": "BranchService"
    }
  ],
  "schemes": ["https"],
  "consumes": ["application/json"],
  "produces": ["application/json"],
  "paths": {
    "/api/v1/serverless/orgs/{org_id}/projects/{project_id}/clusters/{cluster_id}/branches": {
      "get": {
        "summary": "List all branches in the cluster.",
        "operationId": "ListBranches",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/console.ListBranchesResp"
            }
          },
          "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"
          },
          {
            "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
          }
        ],
        "tags": ["BranchService"]
      },
      "post": {
        "summary": "Create a branch.",
        "operationId": "CreateBranch",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/console.CreateBranchResp"
            }
          },
          "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"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/console.BranchService.CreateBranchBody"
            }
          }
        ],
        "tags": ["BranchService"]
      }
    },
    "/api/v1/serverless/orgs/{org_id}/projects/{project_id}/clusters/{cluster_id}/branches/{branch_id}": {
      "get": {
        "summary": "Get a branch.",
        "operationId": "GetBranch",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/console.Branch"
            }
          },
          "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"
          },
          {
            "name": "branch_id",
            "description": "The id of creating branch.",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["BranchService"]
      },
      "delete": {
        "summary": "Delete a branch.",
        "operationId": "DeleteBranch",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/console.DeleteBranchResp"
            }
          },
          "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"
          },
          {
            "name": "branch_id",
            "description": "The name of creating branch.",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["BranchService"]
      },
      "patch": {
        "summary": "Update a branch.",
        "operationId": "UpdateBranch",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/DefaultResp"
            }
          },
          "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"
          },
          {
            "name": "branch_id",
            "description": "The ID of the branch.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "branch",
            "in": "body",
            "required": true,
            "schema": {
              "description": "The branch to update.",
              "$ref": "#/definitions/UpdateBranchReq.Branch"
            }
          }
        ],
        "tags": ["BranchService"]
      }
    },
    "/api/v1/serverless/orgs/{org_id}/projects/{project_id}/clusters/{cluster_id}/branches/{branch_id}/databases": {
      "get": {
        "summary": "List databases of a branch.",
        "operationId": "ListBranchDatabases",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/BranchListDatabasesResp"
            }
          },
          "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"
          },
          {
            "name": "branch_id",
            "description": "The ID of the branch.",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["BranchService"]
      }
    },
    "/api/v1/serverless/orgs/{org_id}/projects/{project_id}/clusters/{cluster_id}/branches/{branch_id}/password": {
      "put": {
        "summary": "Change root password of a branch.",
        "operationId": "ChangePassword",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/DefaultResp"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "org_id",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "cluster_id",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "branch_id",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "password",
            "in": "query",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["BranchService"]
      }
    },
    "/api/v1/serverless/orgs/{org_id}/projects/{project_id}/clusters/{cluster_id}/branches/{branch_id}:reset": {
      "post": {
        "summary": "Reset a branch to its parent.",
        "operationId": "ResetBranch",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/DefaultResp"
            }
          },
          "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"
          },
          {
            "name": "branch_id",
            "description": "The name of creating branch.",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["BranchService"]
      }
    }
  },
  "definitions": {
    "Any": {
      "type": "object",
      "additionalProperties": {},
      "properties": {
        "@type": {
          "type": "string"
        }
      }
    },
    "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"
        }
      }
    },
    "BranchListDatabasesResp": {
      "type": "object",
      "properties": {
        "databases": {
          "description": "The items of databases in the branch.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      },
      "required": ["databases", "base_resp"]
    },
    "DefaultResp": {
      "type": "object",
      "properties": {
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      },
      "required": ["base_resp"]
    },
    "Status": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/Any"
          }
        }
      }
    },
    "UpdateBranchReq.Branch": {
      "type": "object",
      "properties": {
        "display_name": {
          "description": "The display name of the branch.",
          "type": "string"
        }
      }
    },
    "Usages": {
      "type": "object",
      "properties": {
        "request_unit": {
          "type": "string",
          "format": "int64"
        },
        "row_storage": {
          "type": "string",
          "format": "int64"
        },
        "column_storage": {
          "type": "string",
          "format": "int64"
        }
      }
    },
    "console.AuthorizedNetwork": {
      "type": "object",
      "properties": {
        "display_name": {
          "type": "string"
        },
        "start_ip_address": {
          "type": "string"
        },
        "end_ip_address": {
          "type": "string"
        }
      }
    },
    "console.BasicBranch": {
      "description": "BranchItem is the information of branch.",
      "type": "object",
      "properties": {
        "id": {
          "description": "The ID of the branch.",
          "type": "string"
        },
        "name": {
          "description": "The name of the branch.",
          "type": "string"
        },
        "display_name": {
          "description": "The display name of the branch.",
          "type": "string"
        },
        "cluster_id": {
          "description": "The ID of the cluster.",
          "type": "string"
        },
        "parent_id": {
          "description": "The ID of the parent branch.",
          "type": "string"
        },
        "state": {
          "description": "The state of the branch.",
          "$ref": "#/definitions/console.BranchState"
        },
        "usages": {
          "description": "The usages of the branch.",
          "$ref": "#/definitions/Usages"
        },
        "endpoints": {
          "description": "The endpoint of the branch.",
          "$ref": "#/definitions/console.Endpoints"
        },
        "user_prefix": {
          "description": "The userPrefix of the branch.",
          "type": "string"
        },
        "create_time": {
          "description": "The create timestamp of the branch.",
          "type": "string",
          "format": "date-time"
        },
        "update_time": {
          "description": "The update timestamp of the branch.",
          "type": "string",
          "format": "date-time"
        },
        "has_set_pwd": {
          "description": "If the password of the branch has been set.",
          "type": "boolean"
        },
        "parent_display_name": {
          "description": "The display name of the parent.",
          "type": "string"
        },
        "parent_timestamp": {
          "description": "The parent timestamp of the branch.",
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "name",
        "display_name",
        "cluster_id",
        "parent_id",
        "parent_display_name",
        "state",
        "usages",
        "endpoints",
        "user_prefix",
        "create_time",
        "update_time",
        "has_set_pwd"
      ],
      "title": "BranchItem"
    },
    "console.Branch": {
      "description": "BranchItem is the information of branch.",
      "type": "object",
      "properties": {
        "id": {
          "description": "The ID of the branch.",
          "type": "string"
        },
        "name": {
          "description": "The name of the branch.",
          "type": "string"
        },
        "display_name": {
          "description": "The display name of the branch.",
          "type": "string"
        },
        "cluster_id": {
          "description": "The ID of the cluster.",
          "type": "string"
        },
        "parent_id": {
          "description": "The parent ID of the branch.",
          "type": "string"
        },
        "state": {
          "description": "The status of the branch.",
          "$ref": "#/definitions/console.BranchState"
        },
        "endpoints": {
          "description": "The endpoint of the branch.",
          "$ref": "#/definitions/console.Endpoints"
        },
        "user_prefix": {
          "description": "The userPrefix of the branch.",
          "type": "string"
        },
        "usages": {
          "description": "The usages of the branch.",
          "$ref": "#/definitions/Usages"
        },
        "create_time": {
          "description": "The creation timestamp of the branch.",
          "type": "string",
          "format": "date-time"
        },
        "update_time": {
          "description": "The update timestamp of the branch.",
          "type": "string",
          "format": "date-time"
        },
        "annotations": {
          "description": "The annotations of the branch.",
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "has_set_pwd": {
          "description": "If the password of the branch has been set.",
          "type": "boolean"
        },
        "parent_display_name": {
          "description": "The display name of the parent.",
          "type": "string"
        },
        "parent_timestamp": {
          "description": "The parent timestamp of the branch.",
          "type": "string",
          "format": "date-time"
        },
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      },
      "required": [
        "id",
        "name",
        "display_name",
        "cluster_id",
        "parent_id",
        "parent_display_name",
        "state",
        "endpoints",
        "user_prefix",
        "usages",
        "create_time",
        "update_time",
        "has_set_pwd",
        "annotations",
        "base_resp"
      ],
      "title": "BranchItem"
    },
    "console.BranchService.CreateBranchBody": {
      "type": "object",
      "properties": {
        "display_name": {
          "description": "The name of the creating branch. It must be 1-64 characters long.",
          "type": "string",
          "example": "hello"
        },
        "parent_id": {
          "description": "The ID of the parent branch.",
          "type": "string"
        },
        "parent_timestamp": {
          "description": "The parent timestamp of the branch.",
          "type": "string",
          "format": "date-time",
          "example": "2020-01-01T00:00:00Z"
        }
      },
      "required": ["display_name"]
    },
    "console.BranchState": {
      "type": "string",
      "enum": ["CREATING", "READY", "DELETED", "MAINTENANCE", "ACTIVE", "RESTORING"]
    },
    "console.CreateBranchResp": {
      "type": "object",
      "properties": {
        "id": {
          "description": "The ID of the branch.",
          "type": "string",
          "example": "bran-hpprncwwdnavfbnqhav5kk3h5m"
        },
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      },
      "required": ["id", "base_resp"]
    },
    "console.DeleteBranchResp": {
      "type": "object",
      "properties": {
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      },
      "required": ["base_resp"]
    },
    "console.Endpoints": {
      "type": "object",
      "properties": {
        "public_endpoint": {
          "$ref": "#/definitions/console.PublicEndpoint"
        },
        "private_endpoint": {
          "$ref": "#/definitions/console.PrivateEndpoint"
        }
      }
    },
    "console.ListBranchesResp": {
      "type": "object",
      "properties": {
        "branches": {
          "description": "The items of branches in the cluster.",
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/console.BasicBranch"
          }
        },
        "total": {
          "description": "The total number of branches in the cluster.",
          "type": "integer",
          "format": "int64"
        },
        "base_resp": {
          "$ref": "#/definitions/BaseResp"
        }
      },
      "required": ["branches", "total", "base_resp"]
    },
    "console.PrivateEndpoint": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string"
        },
        "port": {
          "type": "integer",
          "format": "int32"
        },
        "disabled": {
          "type": "boolean"
        },
        "aws": {
          "$ref": "#/definitions/console.PrivateEndpointAws"
        },
        "gcp": {
          "$ref": "#/definitions/console.PrivateEndpointGcp"
        }
      }
    },
    "console.PrivateEndpointAws": {
      "type": "object",
      "properties": {
        "service_mame": {
          "type": "string"
        },
        "availability_zone": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "console.PrivateEndpointGcp": {
      "type": "object",
      "properties": {
        "target_service_attachment": {
          "type": "string"
        }
      }
    },
    "console.PublicEndpoint": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string"
        },
        "port": {
          "type": "integer",
          "format": "int32"
        },
        "disabled": {
          "type": "boolean"
        },
        "authorized_networks": {
          "description": "The authorized networks of the public endpoint.",
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/console.AuthorizedNetwork"
          }
        }
      }
    }
  },
  "securityDefinitions": {
    "bearer": {
      "type": "apiKey",
      "description": "Authentication token, prefixed by Bearer: 'Bearer token'",
      "name": "Authorization",
      "in": "header"
    }
  }
}