PingCAP Branch API

openapi: 3.2.0
info:
  title: TiDB Cloud Starter and Essential Branch API
  description: '*TiDB Cloud API is in beta.*


    This API manages TiDB Cloud Starter and TiDB Cloud Essential instances.'
  version: v1beta1
servers:
- url: https://serverless.tidbapi.com/v1beta1
tags:
- name: Branch
paths:
  /clusters/{clusterId}/branches:
    get:
      summary: List branches
      operationId: BranchService_ListBranches
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1ListBranchesResponse'
        '400':
          description: A request field is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '401':
          description: The API key cannot be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '403':
          description: The API key does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '429':
          description: You have exceed the rate limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: clusterId
        description: The ID of the TiDB Cloud Starter or Essential instance to which the [branch](https://docs.pingcap.com/tidbcloud/branch-overview/) belongs.
        in: path
        required: true
        schema:
          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
        schema:
          type: integer
          format: int32
          default: 10
          maximum: 100
          minimum: 1
      - 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.


          **Note**: When paginating, all other parameters must match the original request.'
        in: query
        required: false
        schema:
          type: string
      tags:
      - Branch
      x-codeSamples:
      - label: curl
        lang: cURL
        source: 'curl --location ''https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/branches'' \

          --digest --user ''YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY'' \

          --header ''Accept: application/json'''
    post:
      summary: Create a branch
      operationId: BranchService_CreateBranch
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Branch'
        '400':
          description: A request field is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '401':
          description: The API key cannot be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '403':
          description: The API key does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '429':
          description: You have exceed the rate limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: clusterId
        description: The ID of the TiDB Cloud Starter or Essential instance to which the branch belongs.
        in: path
        required: true
        schema:
          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 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n    \"displayName\": \"test\"\n}'"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1beta1Branch'
        description: The branch being created.
        required: true
  /clusters/{clusterId}/branches/{branchId}:
    get:
      summary: Get details of a branch
      operationId: BranchService_GetBranch
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Branch'
        '400':
          description: A request field is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '401':
          description: The API key cannot be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '403':
          description: The API key does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '429':
          description: You have exceed the rate limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: clusterId
        description: The ID of the TiDB Cloud Starter or Essential instance to which the branch belongs.
        in: path
        required: true
        schema:
          type: string
      - name: branchId
        description: The ID of the branch.
        in: path
        required: true
        schema:
          type: string
      - name: view
        description: 'The detail level of the branch information to return.


          - `BASIC`: returns only basic branch information.

          - `FULL`: returns complete branch details.'
        in: query
        required: false
        schema:
          type: string
          enum:
          - BASIC
          - FULL
          default: FULL
      tags:
      - Branch
      x-codeSamples:
      - label: curl
        lang: cURL
        source: 'curl --location ''https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/branches/{branch_id}'' \

          --digest --user ''YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY'' \

          --header ''Accept: application/json'''
    delete:
      summary: Delete a branch
      operationId: BranchService_DeleteBranch
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Branch'
        '400':
          description: A request field is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '401':
          description: The API key cannot be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '403':
          description: The API key does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '429':
          description: You have exceed the rate limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: clusterId
        description: The ID of the TiDB Cloud Starter or Essential instance to which the branch belongs.
        in: path
        required: true
        schema:
          type: string
      - name: branchId
        description: The ID of the branch.
        in: path
        required: true
        schema:
          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}'' \

          --digest --user ''YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY'' \

          --header ''Accept: application/json'''
  /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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Branch'
        '400':
          description: A request field is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '401':
          description: The API key cannot be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '403':
          description: The API key does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '429':
          description: You have exceed the rate limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: clusterId
        description: The ID of the TiDB Cloud Starter or Essential instance to which the branch belongs.
        in: path
        required: true
        schema:
          type: string
      - name: branchId
        description: The ID of the branch.
        in: path
        required: true
        schema:
          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'' \

          --digest --user ''YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY'' \

          --header ''Accept: application/json'''
components:
  schemas:
    v1beta1BranchEndpointsPrivate:
      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: '#/components/schemas/v1beta1BranchEndpointsPrivateAWS'
      description: Message for Private Endpoint for this branch.
    v1beta1BranchState:
      type: string
      enum:
      - CREATING
      - ACTIVE
      - DELETED
      - RESTORING
      description: "Branch State.\n\n - CREATING: The branch is creating.\n - ACTIVE: The branch is active and running.\n - DELETED: The branch is deleted.\n - RESTORING: The branch is restoring."
    v1beta1BranchEndpointsPrivateAWS:
      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.
    googlerpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: The error code returned with this error.
        message:
          type: string
          description: The error message returned with this error.
        details:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/protobufAny'
          description: A list of messages with additional error details.
      description: 'The `Status` type defines a logical error model that is suitable for

        different programming environments, including REST APIs and RPC APIs. It is

        used by [gRPC](https://github.com/grpc). Each `Status` message contains

        three pieces of data: error code, error message, and error details.


        You can find out more about this error model and how to work with it in the

        [API Design Guide](https://cloud.google.com/apis/design/errors).'
    v1beta1BranchEndpointsPublic:
      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: '#/components/schemas/v1beta1BranchEndpointsPublicAuthorizedNetwork'
          description: The list of networks that are allowed to connect to the branch.
          readOnly: true
      description: Message for Public Endpoint for this branch.
    v1beta1ListBranchesResponse:
      type: object
      properties:
        branches:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/v1beta1Branch'
          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.
    v1beta1BranchEndpointsPublicAuthorizedNetwork:
      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.
    v1beta1BranchEndpoints:
      type: object
      properties:
        public:
          description: The public endpoint configuration for connecting to the branch.
          allOf:
          - $ref: '#/components/schemas/v1beta1BranchEndpointsPublic'
        private:
          description: The private endpoint for securely connecting to the branch.
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/v1beta1BranchEndpointsPrivate'
      description: Message for the Endpoints for this branch.
    protobufAny:
      type: object
      properties:
        '@type':
          type: string
          description: A URL or resource name that uniquely identifies the type of the serialized protocol buffer message.
      additionalProperties: {}
      description: "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n    Foo foo = ...;\n    Any any;\n    any.PackFrom(foo);\n    ...\n    if (any.UnpackTo(&foo)) {\n      ...\n    }\n\nExample 2: Pack and unpack a message in Java.\n\n    Foo foo = ...;\n    Any any = Any.pack(foo);\n    ...\n    if (any.is(Foo.class)) {\n      foo = any.unpack(Foo.class);\n    }\n    // or ...\n    if (any.isSameTypeAs(Foo.getDefaultInstance())) {\n      foo = any.unpack(Foo.getDefaultInstance());\n    }\n\n Example 3: Pack and unpack a message in Python.\n\n    foo = Foo(...)\n    any = Any()\n    any.Pack(foo)\n    ...\n    if any.Is(Foo.DESCRIPTOR):\n      any.Unpack(foo)\n      ...\n\n Example 4: Pack and unpack a message in Go\n\n     foo := &pb.Foo{...}\n     any, err := anypb.New(foo)\n     if err != nil {\n       ...\n     }\n     ...\n     foo := &pb.Foo{}\n     if err := any.UnmarshalTo(foo); err != nil {\n       ...\n     }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n    package google.profile;\n    message Person {\n      string first_name = 1;\n      string last_name = 2;\n    }\n\n    {\n      \"@type\": \"type.googleapis.com/google.profile.Person\",\n      \"firstName\": <string>,\n      \"lastName\": <string>\n    }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n    {\n      \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n      \"value\": \"1.212s\"\n    }"
    v1beta1Branch:
      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 TiDB Cloud Starter or Essential instance 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: '#/components/schemas/v1beta1BranchState'
        endpoints:
          description: The connection endpoints for accessing the branch.
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/v1beta1BranchEndpoints'
        userPrefix:
          type:
          - string
          - 'null'
          description: The unique prefix automatically generated for SQL usernames on this TiDB Cloud Starter or Essential instance. TiDB Cloud uses this prefix to distinguish between TiDB Cloud Starter and Essential instances. 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
          - 'null'
          format: date-time
          description: The point in time on the parent branch from which the branch is created. The timestamp is truncated to seconds without rounding.
      description: Message for branch.
      required:
      - displayName