{
  "swagger": "2.0",
  "info": {
    "title": "TiDB Cloud Starter and Essential API",
    "description": "TiDB Cloud Starter and Essential API",
    "version": "v1beta1"
  },
  "tags": [
    {
      "name": "BranchService"
    }
  ],
  "host": "serverless.tidbapi.com",
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/v1beta1/clusters/{clusterId}/branches": {
      "get": {
        "summary": "List branches",
        "operationId": "BranchService_ListBranches",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/ListBranchesResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "The ID of the cluster to which the [branch](https://docs.pingcap.com/tidbcloud/branch-overview/) belongs.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "pageSize",
            "description": "The maximum number of branches to return. If not specified, at most 10 branches will be returned. The maximum value is `100`. Values greater than `100` are set to `100`.",
            "in": "query",
            "required": false,
            "type": "integer",
            "format": "int32",
            "default": 10
          },
          {
            "name": "pageToken",
            "description": "The pagination token received from a previous [List branches](#tag/Branch/operation/BranchService_ListBranches) request. Use this token to retrieve the next page of results.\n\n**Note**: When paginating, all other parameters must match the original request.",
            "in": "query",
            "required": false,
            "type": "string"
          }
        ],
        "tags": [
          "Branch"
        ],
        "x-codeSamples": [
          {
            "label": "curl",
            "lang": "cURL",
            "source": "curl --location 'https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/branches' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'"
          }
        ]
      },
      "post": {
        "summary": "Creates a branch",
        "operationId": "BranchService_CreateBranch",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/Branch"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "The ID of the cluster to which the branch belongs.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "branch",
            "description": "The branch being created.",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/Branch"
            }
          }
        ],
        "tags": [
          "Branch"
        ],
        "x-codeSamples": [
          {
            "label": "curl",
            "lang": "cURL",
            "source": "curl --location 'https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/branches' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n    \"displayName\": \"test\"\n}'"
          }
        ]
      }
    },
    "/v1beta1/clusters/{clusterId}/branches/{branchId}": {
      "get": {
        "summary": "Get detail of a branch",
        "operationId": "BranchService_GetBranch",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/Branch"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "The ID of the cluster to which the branch belongs.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "branchId",
            "description": "The ID of the branch.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "view",
            "description": "The detail level of the branch information to return. Default value is `FULL`.\n\n- `BASIC`: returns only basic branch information.\n- `FULL`: returns complete branch details.",
            "in": "query",
            "required": false,
            "type": "string",
            "enum": [
              "BASIC",
              "FULL"
            ]
          }
        ],
        "tags": [
          "Branch"
        ],
        "x-codeSamples": [
          {
            "label": "curl",
            "lang": "cURL",
            "source": "curl --location 'https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/branches/{branch_id}' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'"
          }
        ]
      },
      "delete": {
        "summary": "Delete a branch",
        "operationId": "BranchService_DeleteBranch",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/Branch"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "The ID of the cluster to which the branch belongs.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "branchId",
            "description": "The ID of the branch.",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "tags": [
          "Branch"
        ],
        "x-codeSamples": [
          {
            "label": "curl",
            "lang": "cURL",
            "source": "curl --location --request DELETE 'https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/branches/{branch_id}' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'"
          }
        ]
      }
    },
    "/v1beta1/clusters/{clusterId}/branches/{branchId}:reset": {
      "post": {
        "summary": "Reset a branch",
        "description": "Resets a branch to match the current state of its parent branch.",
        "operationId": "BranchService_ResetBranch",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/Branch"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "The ID of the cluster to which the branch belongs.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "branchId",
            "description": "The ID of the branch.",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "tags": [
          "Branch"
        ],
        "x-codeSamples": [
          {
            "label": "curl",
            "lang": "cURL",
            "source": "curl --location --request POST 'https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/branches/{branch_id}:reset' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'"
          }
        ]
      }
    },
    "/v1beta1/clusters/{clusterId}/branches/{branchId}/sqlUsers/{username}": {
      "patch": {
        "summary": "Update a branch sql user",
        "operationId": "BranchService_UpdateSqlUser",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/SqlUser"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "The ID of the cluster to which the branch belongs.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "branchId",
            "description": "The ID of the branch.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "username",
            "description": "The username of the branch sql user.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BranchService.UpdateSqlUserBody"
            }
          }
        ],
        "tags": [
          "Branch"
        ],
        "x-codeSamples": [
          {
            "label": "curl",
            "lang": "cURL",
            "source": "curl --location 'https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/branches/{branch_id}/sqlUsers/{username}' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n    \"password\": \"test1234\"\n}'"
          }
        ]
      }
    }
  },
  "definitions": {
    "Any": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "string"
        }
      },
      "additionalProperties": {}
    },
    "Branch": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique identifier for the branch.",
          "readOnly": true
        },
        "branchId": {
          "type": "string",
          "description": "The system-generated ID of the branch.",
          "readOnly": true
        },
        "displayName": {
          "type": "string",
          "description": "The user-defined name of the branch."
        },
        "clusterId": {
          "type": "string",
          "description": "The ID of the cluster to which the branch belongs.",
          "readOnly": true
        },
        "parentId": {
          "type": "string",
          "description": "The ID of the branch parent."
        },
        "createdBy": {
          "type": "string",
          "description": "The email address of the user who create the branch.",
          "readOnly": true
        },
        "state": {
          "description": "The state of the branch.",
          "readOnly": true,
          "allOf": [
            {
              "$ref": "#/definitions/Branch.State"
            }
          ]
        },
        "endpoints": {
          "description": "The connection endpoints for accessing the branch.",
          "readOnly": true,
          "allOf": [
            {
              "$ref": "#/definitions/Branch.Endpoints"
            }
          ]
        },
        "userPrefix": {
          "type": "string",
          "x-nullable": true,
          "description": "The unique prefix automatically generated for SQL usernames on this cluster. TiDB Cloud uses this prefix to distinguish between clusters. For more information, see [User name prefix](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#user-name-prefix).",
          "readOnly": true
        },
        "createTime": {
          "type": "string",
          "format": "date-time",
          "description": "The timestamp when the branch was created, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.",
          "readOnly": true
        },
        "updateTime": {
          "type": "string",
          "format": "date-time",
          "description": "The timestamp when the branch was last updated, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.",
          "readOnly": true
        },
        "annotations": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "The annotations for the branch."
        },
        "parentDisplayName": {
          "type": "string",
          "description": "The display name of the parent branch from which the branch was created.",
          "readOnly": true
        },
        "parentTimestamp": {
          "type": "string",
          "format": "date-time",
          "x-nullable": true,
          "description": "The point in time on the parent branch from which the branch is created. The timestamp is truncated to seconds without rounding."
        },
        "rootPassword": {
          "type": "string",
          "example": "my-shining-password",
          "description": "The root password of the branch. It must be between 8 and 64 characters long and can contain letters, numbers, and special characters.",
          "maxLength": 64,
          "minLength": 8,
          "pattern": "^.{8,64}$"
        }
      },
      "description": "Message for branch.",
      "required": [
        "displayName"
      ]
    },
    "Branch.Endpoints": {
      "type": "object",
      "properties": {
        "public": {
          "description": "The public endpoint configuration for connecting to the branch.",
          "allOf": [
            {
              "$ref": "#/definitions/Branch.Endpoints.Public"
            }
          ]
        },
        "private": {
          "description": "The private endpoint for securely connecting to the branch.",
          "readOnly": true,
          "allOf": [
            {
              "$ref": "#/definitions/Branch.Endpoints.Private"
            }
          ]
        }
      },
      "description": "Message for the Endpoints for this branch."
    },
    "Branch.Endpoints.Private": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "description": "The hostname of the private endpoint.",
          "readOnly": true
        },
        "port": {
          "type": "integer",
          "format": "int32",
          "description": "The port number of the private endpoint.",
          "readOnly": true
        },
        "aws": {
          "description": "The [AWS PrivateLink](https://aws.amazon.com/privatelink/) configuration details for private access.",
          "readOnly": true,
          "allOf": [
            {
              "$ref": "#/definitions/Branch.Endpoints.Private.AWS"
            }
          ]
        },
        "gcp": {
          "title": "Message for GCP",
          "readOnly": true,
          "allOf": [
            {
              "$ref": "#/definitions/Branch.Endpoints.Private.GCP"
            }
          ]
        }
      },
      "description": "Message for Private Endpoint for this branch."
    },
    "Branch.Endpoints.Private.AWS": {
      "type": "object",
      "properties": {
        "serviceName": {
          "type": "string",
          "description": "The AWS service name for private access.",
          "readOnly": true
        },
        "availabilityZone": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "A list of availability zones where the service is available.",
          "readOnly": true
        }
      },
      "description": "Message for AWS Private Link Service."
    },
    "Branch.Endpoints.Private.GCP": {
      "type": "object",
      "properties": {
        "serviceAttachmentName": {
          "type": "string",
          "description": "Target Service Account for Private Link Service.",
          "readOnly": true
        }
      },
      "description": "Message for GCP Private Link Service."
    },
    "Branch.Endpoints.Public": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "description": "The hostname of the public endpoint.",
          "readOnly": true
        },
        "port": {
          "type": "integer",
          "format": "int32",
          "description": "The port number of the public endpoint.",
          "readOnly": true
        },
        "disabled": {
          "type": "boolean",
          "description": "Indicates whether the public endpoint is disabled."
        },
        "authorizedNetworks": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/Branch.Endpoints.Public.AuthorizedNetwork"
          },
          "description": "The list of networks that are allowed to connect to the branch.",
          "readOnly": true
        }
      },
      "description": "Message for Public Endpoint for this branch."
    },
    "Branch.Endpoints.Public.AuthorizedNetwork": {
      "type": "object",
      "properties": {
        "displayName": {
          "type": "string",
          "description": "The display name of the authorized network."
        },
        "startIpAddress": {
          "type": "string",
          "description": "The starting IP address of the authorized network range."
        },
        "endIpAddress": {
          "type": "string",
          "description": "The ending IP address of the authorized network range."
        }
      }
    },
    "Branch.State": {
      "type": "string",
      "enum": [
        "CREATING",
        "ACTIVE",
        "DELETED",
        "RESTORING"
      ],
      "description": "Branch State.\n\n - CREATING: The branch is being created.\n - ACTIVE: The branch is active and running.\n - DELETED: The branch is being deleted.\n - RESTORING: The branch is restoring."
    },
    "BranchService.UpdateSqlUserBody": {
      "type": "object",
      "properties": {
        "password": {
          "type": "string",
          "example": "my-shining-password",
          "description": "The password of the sql user. It must be between 8 and 64 characters long and can contain letters, numbers, and special characters.",
          "maxLength": 64,
          "minLength": 8,
          "pattern": "^.{8,64}$"
        }
      }
    },
    "BranchView": {
      "type": "string",
      "enum": [
        "BASIC",
        "FULL"
      ],
      "description": "View on branch. Pass this enum to control which subsets of fields to get."
    },
    "ListBranchesResponse": {
      "type": "object",
      "properties": {
        "branches": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/Branch"
          },
          "description": "A list of branches that match the query."
        },
        "nextPageToken": {
          "type": "string",
          "description": "The token to retrieve the next page of results. Use this value as the `pageToken` parameter in the next request. This field is empty when there are no more pages."
        },
        "totalSize": {
          "type": "integer",
          "format": "int64",
          "description": "The total number of branches that match the query."
        }
      },
      "description": "Message for response to list branches."
    },
    "SqlUser": {
      "type": "object",
      "properties": {
        "username": {
          "type": "string",
          "description": "The username of the branch sql user."
        }
      },
      "required": [
        "username"
      ]
    },
    "Status": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/Any"
          }
        }
      }
    }
  }
}