openapi: 3.1.0
info:
  title: TiDB Cloud API Keys Status API
  description: The TiDB Cloud API is a REST interface that provides programmatic access to manage administrative objects within TiDB Cloud. It supports managing projects, clusters, backups, restores, data imports, billing, and private endpoint connections across both TiDB Cloud Serverless and TiDB Cloud Dedicated tiers. The API uses HTTP Digest Authentication with public and private API keys and returns JSON-formatted responses. Available as both v1beta and the newer v1beta1 versions, it enables automation of database infrastructure lifecycle management at scale.
  version: v1beta1
  contact:
    name: TiDB Cloud Support
    url: https://docs.pingcap.com/tidbcloud/api-overview/
  termsOfService: https://www.pingcap.com/legal/privacy-policy/
servers:
- url: https://dedicated.tidbapi.com/v1beta1
  description: Dedicated Cluster API Server
- url: https://iam.tidbapi.com/v1beta1
  description: IAM API Server
- url: https://billing.tidbapi.com/v1beta1
  description: Billing API Server
security:
- digestAuth: []
tags:
- name: Status
  description: Endpoints for retrieving the operational status of the TiDB server instance.
paths:
  /status:
    get:
      operationId: getServerStatus
      summary: Get server status
      description: Returns the current operational status of the TiDB server instance, including the number of active connections, the TiDB version string, and the git commit hash of the binary. This endpoint is commonly used by load balancers and health check systems to verify that the TiDB process is running and accepting connections.
      tags:
      - Status
      responses:
        '200':
          description: Server status retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerStatus'
  /metrics:
    get:
      operationId: getMetrics
      summary: Get Prometheus metrics
      description: Returns all Prometheus-format performance metrics for the TiDB server instance. This endpoint is consumed by Prometheus scrape jobs to collect TiDB-specific metrics including query latency, error rates, connection pool utilization, and internal component performance counters.
      tags:
      - Status
      responses:
        '200':
          description: Prometheus metrics returned in text exposition format.
          content:
            text/plain:
              schema:
                type: string
                description: Prometheus text format metrics output.
  /info:
    get:
      operationId: getServerInfo
      summary: Get server information
      description: Returns detailed information about the TiDB server instance including version, IP address, listening port, status port, and the git hash of the binary. This endpoint is useful for service discovery and identifying specific nodes in a TiDB cluster.
      tags:
      - Status
      responses:
        '200':
          description: Server information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerInfo'
  /info/all:
    get:
      operationId: getAllServersInfo
      summary: Get all cluster server information
      description: Returns information about all TiDB server instances in the cluster as registered with the Placement Driver (PD). This provides a cluster-wide view of all running TiDB nodes and their connection endpoints.
      tags:
      - Status
      responses:
        '200':
          description: All TiDB server information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllServersInfo'
components:
  schemas:
    ServerStatus:
      type: object
      description: Current operational status of the TiDB server instance.
      properties:
        connections:
          type: integer
          description: The number of currently active client connections.
        version:
          type: string
          description: The TiDB server version string.
        git_hash:
          type: string
          description: The git commit hash of the running TiDB binary.
    AllServersInfo:
      type: object
      description: Information about all TiDB nodes in the cluster.
      properties:
        servers_num:
          type: integer
          description: The total number of TiDB servers in the cluster.
        owner_id:
          type: string
          description: The DDL ID of the current DDL owner node.
        is_all_server_version_consistent:
          type: boolean
          description: Whether all TiDB servers are running the same version.
        all_servers_info:
          type: object
          description: A map of server DDL IDs to their ServerInfo objects.
          additionalProperties:
            $ref: '#/components/schemas/ServerInfo'
    ServerInfo:
      type: object
      description: Detailed information about the TiDB server instance.
      properties:
        ddl_id:
          type: string
          description: The unique DDL identifier for this TiDB node.
        ip:
          type: string
          description: The IP address of this TiDB node.
        listening_port:
          type: integer
          description: The SQL connection port this node listens on.
        status_port:
          type: integer
          description: The HTTP status port this node listens on.
        lease:
          type: string
          description: The schema lease duration string.
        binlog_status:
          type: string
          description: The current binlog pump connection status.
        start_timestamp:
          type: integer
          description: The Unix timestamp when this TiDB server started.
        git_hash:
          type: string
          description: The git commit hash of the TiDB binary.
        is_owner:
          type: boolean
          description: Whether this TiDB node is the current DDL owner.
        op_scope_level:
          type: integer
          description: The scope level for this server's operational range.
  securitySchemes:
    digestAuth:
      type: http
      scheme: digest
      description: HTTP Digest Authentication using a TiDB Cloud API public key as the username and private key as the password. Keys are generated in the TiDB Cloud console under Organization Settings > API Keys.
externalDocs:
  description: TiDB Cloud API Overview
  url: https://docs.pingcap.com/tidbcloud/api-overview/