TiDB HTTP API

openapi: 3.1.0
info:
  title: TiDB HTTP API
  description: >-
    The TiDB HTTP API is a built-in administrative interface available on
    self-managed TiDB server instances, accessible on port 10080 by default.
    It exposes endpoints for retrieving server status, database and table schema
    information, region metadata, MVCC key details, DDL job history, hot region
    data, and server configuration. Operators and monitoring systems use this API
    to inspect the internal state of a running TiDB node, integrate with
    observability tooling, and troubleshoot distributed SQL execution. The API
    does not require authentication by default and is intended for use within
    trusted internal networks. The port can be configured in tidb.toml via the
    status.status-port setting.
  version: '1.0'
  contact:
    name: TiDB GitHub
    url: https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md
  termsOfService: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
  description: TiDB HTTP API Reference
  url: https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md
servers:
  - url: http://localhost:10080
    description: Local TiDB Node (default status port)
tags:
  - name: DDL
    description: Endpoints for managing and inspecting DDL jobs, including ownership and history.
  - name: Diagnostics
    description: Endpoints for downloading debug information and managing server diagnostics.
  - name: MVCC
    description: Endpoints for retrieving multi-version concurrency control (MVCC) key details for debugging.
  - name: Regions
    description: Endpoints for retrieving TiKV region metadata associated with tables and the cluster.
  - name: Schema
    description: Endpoints for retrieving database and table schema information from the TiDB information schema.
  - name: Settings
    description: Endpoints for retrieving and modifying TiDB server runtime settings.
  - name: Statistics
    description: Endpoints for exporting optimizer statistics used for query planning.
  - 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'
  /schema:
    get:
      operationId: getAllSchemas
      summary: Get all database schemas
      description: >-
        Returns schema information for all databases known to this TiDB instance.
        The response includes table names, column definitions, and index
        information as represented in the TiDB information schema.
      tags:
        - Schema
      responses:
        '200':
          description: All database schemas retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DatabaseSchema'
  /schema/{db}:
    get:
      operationId: getDatabaseSchema
      summary: Get database schema
      description: >-
        Returns schema information for all tables in the specified database.
        Optionally set id_name_only to true to return only table IDs and names
        without the full column and index details, which is faster for large
        schemas.
      tags:
        - Schema
      parameters:
        - $ref: '#/components/parameters/db'
        - name: id_name_only
          in: query
          description: If true, returns only table IDs and names without full schema details.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: Database schema retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TableSchema'
        '404':
          description: The specified database was not found.
  /schema/{db}/{table}:
    get:
      operationId: getTableSchema
      summary: Get table schema
      description: >-
        Returns the full schema definition for the specified table, including all
        column names, types, default values, and index definitions. Can also
        look up a table by numeric table_id or multiple table_ids for batch
        retrieval.
      tags:
        - Schema
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/table'
        - name: table_id
          in: query
          description: Optional numeric table ID for lookup by ID instead of name.
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Table schema retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableSchema'
        '404':
          description: The specified database or table was not found.
  /db-table/{tableID}:
    get:
      operationId: getTableByID
      summary: Get table info by table ID
      description: >-
        Returns database information, table information, and the current TiDB
        info schema version for a specific table identified by its numeric table
        ID. This is useful for reverse lookups when you have a table ID from
        region information but need the associated database and table names.
      tags:
        - Schema
      parameters:
        - name: tableID
          in: path
          description: The numeric TiDB internal table ID.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Table information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableByIDResponse'
        '404':
          description: No table with the specified ID was found.
  /regions/meta:
    get:
      operationId: listRegionsMeta
      summary: List all regions metadata
      description: >-
        Returns the metadata for all TiKV regions known to this TiDB instance.
        Each region entry includes region ID, start and end keys, epoch
        information, and peer assignments. This endpoint is primarily used for
        cluster topology inspection and debugging region distribution issues.
      tags:
        - Regions
      responses:
        '200':
          description: Region metadata retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RegionMeta'
  /regions/hot:
    get:
      operationId: getHotRegions
      summary: Get hot regions
      description: >-
        Returns the top hot read and write regions for each TiKV store, along
        with the associated table and index names. This endpoint is used for
        identifying hotspot issues in data access patterns, which can cause
        uneven load distribution across TiKV nodes.
      tags:
        - Regions
      responses:
        '200':
          description: Hot regions data retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotRegions'
  /regions/{regionID}:
    get:
      operationId: getRegionByID
      summary: Get a region
      description: >-
        Returns detailed information about a specific TiKV region identified by
        its numeric region ID. Includes peer locations, epoch, and the associated
        frame information mapping the region to TiDB tables and indexes.
      tags:
        - Regions
      parameters:
        - name: regionID
          in: path
          description: The numeric TiKV region ID.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Region information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionInfo'
        '404':
          description: No region with the specified ID was found.
  /tables/{db}/{table}/regions:
    get:
      operationId: getTableRegions
      summary: Get table regions
      description: >-
        Returns the list of TiKV regions that store data for a specific TiDB
        table. Each region entry includes the region ID, start key, end key,
        leader peer, and follower peers. Use this endpoint to understand the
        physical data layout of a table across TiKV stores.
      tags:
        - Regions
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/table'
      responses:
        '200':
          description: Table regions retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableRegions'
        '404':
          description: The specified database or table was not found.
  /tables/{db}/{table}/scatter:
    post:
      operationId: scatterTableRegions
      summary: Scatter table regions
      description: >-
        Initiates region scatter for the specified table, redistributing its
        TiKV regions across stores to improve data balance. This is typically
        used after bulk data loads that may have caused uneven region distribution.
      tags:
        - Regions
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/table'
      responses:
        '200':
          description: Region scatter initiated successfully.
        '404':
          description: The specified database or table was not found.
  /mvcc/key/{db}/{table}/{handle}:
    get:
      operationId: getMvccByHandle
      summary: Get MVCC info by row handle
      description: >-
        Returns multi-version concurrency control (MVCC) information for the key
        corresponding to the specified row handle in a table. Shows all versions
        of the key across transactions, including start timestamp, commit
        timestamp, and value. Used for debugging transaction conflicts and
        stale data issues.
      tags:
        - MVCC
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/table'
        - name: handle
          in: path
          description: The row handle (primary key value or internal row ID) for the target row.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: MVCC information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MvccInfo'
        '404':
          description: The specified database, table, or handle was not found.
  /mvcc/hex/{hexKey}:
    get:
      operationId: getMvccByHexKey
      summary: Get MVCC info by hex key
      description: >-
        Returns MVCC information for a key specified as a hexadecimal string.
        This endpoint is used when you have the raw encoded key from TiKV region
        information and need to look up the MVCC history for that specific key.
      tags:
        - MVCC
      parameters:
        - name: hexKey
          in: path
          description: The raw key encoded as a hexadecimal string.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: MVCC information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MvccInfo'
  /ddl/history:
    get:
      operationId: getDdlHistory
      summary: Get DDL job history
      description: >-
        Returns the history of DDL (Data Definition Language) jobs executed on
        the cluster, such as CREATE TABLE, ALTER TABLE, DROP INDEX, and similar
        schema change operations. Results are paginated using start_job_id and
        limit parameters. DDL history is useful for auditing schema changes and
        diagnosing failed schema modifications.
      tags:
        - DDL
      parameters:
        - name: start_job_id
          in: query
          description: The DDL job ID to start listing from, for pagination.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: Maximum number of DDL job history records to return.
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: DDL job history retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DdlJob'
  /ddl/owner/resign:
    post:
      operationId: resignDdlOwner
      summary: Resign DDL owner
      description: >-
        Forces the current TiDB server to resign its role as the DDL owner,
        triggering a new DDL owner election among all TiDB servers in the cluster.
        Only one TiDB server is the DDL owner at any time and is responsible for
        executing schema change jobs. Use this endpoint when the current DDL owner
        is experiencing issues.
      tags:
        - DDL
      responses:
        '200':
          description: DDL owner resignation initiated successfully.
  /settings:
    get:
      operationId: getSettings
      summary: Get server settings
      description: >-
        Returns the current runtime settings of the TiDB server instance,
        including log level, general log status, and DDL slow threshold. These
        settings can be modified without restarting the server via the POST method
        of this endpoint.
      tags:
        - Settings
      responses:
        '200':
          description: Server settings retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerSettings'
    post:
      operationId: updateSettings
      summary: Update server settings
      description: >-
        Modifies one or more runtime settings of the TiDB server without
        requiring a restart. Supports updating general_log to enable or disable
        the general query log, log_level to change the server log verbosity, and
        ddl_slow_threshold to adjust the DDL slow operation threshold in
        milliseconds.
      tags:
        - Settings
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateSettingsRequest'
      responses:
        '200':
          description: Server settings updated successfully.
        '400':
          description: Invalid setting name or value provided.
  /stats/dump/{db}/{table}:
    get:
      operationId: dumpTableStats
      summary: Dump table statistics
      description: >-
        Returns the optimizer statistics for the specified table in JSON format.
        Statistics include histogram data, count-min sketch approximations, and
        correlation coefficients used by the TiDB query optimizer when generating
        execution plans. Optionally specify a timestamp to retrieve historical
        statistics.
      tags:
        - Statistics
      parameters:
        - $ref: '#/components/parameters/db'
        - $ref: '#/components/parameters/table'
        - name: timestamp
          in: query
          description: Optional Unix timestamp to retrieve historical statistics at a specific point in time.
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Table statistics dumped successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableStats'
        '404':
          description: The specified database or table was not found.
  /debug/zip:
    get:
      operationId: downloadDebugZip
      summary: Download debug info zip
      description: >-
        Returns a zip archive containing TiDB debug information useful for
        diagnosing production issues. The archive includes heap profile, CPU
        profile, goroutine dump, and configuration information collected over the
        specified number of seconds. This endpoint is used when filing bug reports
        or investigating performance problems with PingCAP support.
      tags:
        - Diagnostics
      parameters:
        - name: seconds
          in: query
          description: Number of seconds to collect CPU profile and goroutine data before packaging.
          required: false
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Debug zip archive returned successfully.
          content:
            application/zip:
              schema:
                type: string
                format: binary
                description: A zip file containing debug information.
components:
  parameters:
    db:
      name: db
      in: path
      description: The database name.
      required: true
      schema:
        type: string
    table:
      name: table
      in: path
      description: The table name within the specified database.
      required: true
      schema:
        type: string
  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.
    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.
    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'
    DatabaseSchema:
      type: object
      description: Schema information for a TiDB database.
      properties:
        db_name:
          $ref: '#/components/schemas/CIStr'
        charset:
          type: string
          description: The character set of the database.
        collate:
          type: string
          description: The collation of the database.
    TableSchema:
      type: object
      description: Schema information for a TiDB table.
      properties:
        id:
          type: integer
          description: The internal numeric TiDB table ID.
        name:
          $ref: '#/components/schemas/CIStr'
        charset:
          type: string
          description: The character set of the table.
        collate:
          type: string
          description: The collation of the table.
        cols:
          type: array
          description: The list of column definitions in the table.
          items:
            $ref: '#/components/schemas/ColumnInfo'
        index_info:
          type: array
          description: The list of index definitions on the table.
          items:
            $ref: '#/components/schemas/IndexInfo'
    ColumnInfo:
      type: object
      description: A column definition within a TiDB table schema.
      properties:
        id:
          type: integer
          description: The internal numeric column ID.
        name:
          $ref: '#/components/schemas/CIStr'
        field_type:
          type: object
          description: The MySQL field type descriptor for this column.
    IndexInfo:
      type: object
      description: An index definition on a TiDB table.
      properties:
        id:
          type: integer
          description: The internal numeric index ID.
        idx_name:
          $ref: '#/components/schemas/CIStr'
        tbl_name:
          $ref: '#/components/schemas/CIStr'
        idx_cols:
          type: array
          description: The columns included in this index.
          items:
            type: object
        is_unique:
          type: boolean
          description: Whether this is a unique index.
        is_primary:
          type: boolean
          description: Whether this is the primary key index.
    CIStr:
      type: object
      description: A case-insensitive string pair used in TiDB schema objects.
      properties:
        O:
          type: string
          description: The original case-preserved string value.
        L:
          type: string
          description: The lowercase version of the string.
    TableByIDResponse:
      type: object
      description: Database and table information looked up by table ID.
      properties:
        db_info:
          $ref: '#/components/schemas/DatabaseSchema'
        table_info:
          $ref: '#/components/schemas/TableSchema'
    RegionMeta:
      type: object
      description: Metadata about a TiKV region.
      properties:
        region_id:
          type: integer
          description: The unique numeric identifier of the region.
        start_key:
          type: string
          description: The encoded start key of the region's key range.
        end_key:
          type: string
          description: The encoded end key of the region's key range.
        frames:
          type: array
          description: The frame mappings associating this region with TiDB tables and indexes.
          items:
            $ref: '#/components/schemas/RegionFrame'
    RegionFrame:
      type: object
      description: A mapping from a TiKV region to a TiDB table or index.
      properties:
        db_name:
          type: string
          description: The database name associated with this region.
        table_name:
          type: string
          description: The table name associated with this region.
        table_id:
          type: integer
          description: The numeric table ID associated with this region.
        is_record:
          type: boolean
          description: Whether this region stores row data (as opposed to index data).
        record_id:
          type: integer
          description: The record ID range start if this region stores row data.
        index_name:
          type: string
          description: The index name if this region stores index data.
        index_id:
          type: integer
          description: The numeric index ID if this region stores index data.
    HotRegions:
      type: object
      description: Hot read and write region data across all TiKV stores.
      properties:
        as_peer:
          type: array
          description: Hot regions where the local store is a follower peer.
          items:
            $ref: '#/components/schemas/HotRegionStore'
        as_leader:
          type: array
          description: Hot regions where the local store is the leader.
          items:
            $ref: '#/components/schemas/HotRegionStore'
    HotRegionStore:
      type: object
      description: Hot region data for a specific TiKV store.
      properties:
        store_id:
          type: integer
          description: The numeric TiKV store ID.
        hot_region_list:
          type: array
          description: The list of hot regions for this store.
          items:
            $ref: '#/components/schemas/HotRegion'
    HotRegion:
      type: object
      description: A hot region with throughput statistics.
      properties:
        region_id:
          type: integer
          description: The region ID.
        flow_bytes:
          type: number
          description: The data throughput through this region in bytes per second.
    RegionInfo:
      type: object
      description: Detailed information about a specific TiKV region.
      properties:
        id:
          type: integer
          description: The unique numeric region ID.
        start_key:
          type: string
          description: The encoded start key of the region.
        end_key:
          type: string
          description: The encoded end key of the region.
        frames:
          type: array
          description: The TiDB table/index mappings for this region.
          items:
            $ref: '#/components/schemas/RegionFrame'
    TableRegions:
      type: object
      description: Region distribution information for a TiDB table.
      properties:
        table_name:
          type: string
          description: The name of the table.
        table_id:
          type: integer
          description: The numeric table ID.
        record_regions:
          type: array
          description: The regions storing row data for this table.
          items:
            $ref: '#/components/schemas/RegionDetail'
        indices:
          type: array
          description: The index regions for this table.
          items:
            $ref: '#/components/schemas/IndexRegions'
    RegionDetail:
      type: object
      description: Details about a specific TiKV region hosting table or index data.
      properties:
        region_id:
          type: integer
          description: The region ID.
        leader:
          $ref: '#/components/schemas/RegionPeer'
        peers:
          type: array
          description: All peer nodes for this region.
          items:
            $ref: '#/components/schemas/RegionPeer'
        start_key:
          type: string
          description: The encoded start key of this region.
        end_key:
          type: string
          description: The encoded end key of this region.
    IndexRegions:
      type: object
      description: Region information for a specific table index.
      properties:
        name:
          type: string
          description: The index name.
        id:
          type: integer
          description: The numeric index ID.
        regions:
          type: array
          description: The regions holding data for this index.
          items:
            $ref: '#/components/schemas/RegionDetail'
    RegionPeer:
      type: object
      description: A peer replica of a TiKV region.
      properties:
        id:
          type: integer
          description: The peer ID.
        store_id:
          type: integer
          description: The TiKV store ID where this peer is hosted.
    MvccInfo:
      type: object
      description: MVCC version history for a TiKV key.
      properties:
        key:
          type: string
          description: The hexadecimal-encoded key.
        mvcc:
          type: object
          description: The MVCC data for this key.
          properties:
            info:
              type: object
              description: Raw MVCC information including lock, writes, and values.
    DdlJob:
      type: object
      description: A DDL job record from TiDB's schema change history.
      properties:
        id:
          type: integer
          description: The unique numeric DDL job ID.
        type:
          type: string
          description: The DDL job type (e.g., create table, add index, drop column).
        schema_id:
          type: integer
          description: The ID of the database schema affected by this DDL job.
        table_id:
          type: integer
          description: The ID of the table affected by this DDL job.
        schema_name:
          type: string
          description: The database name affected by this DDL job.
        table_name:
          type: string
          description: The table name affected by this DDL job.
        state:
          type: string
          description: The current state of the DDL job (done, synced, cancelled, etc.).
        start_time:
          type: integer
          description: The Unix timestamp when the DDL job started.
        error:
          type: string
          description: Error message if the DDL job failed.
    ServerSettings:
      type: object
      description: Current runtime settings of the TiDB server.
      properties:
        general_log:
          type: boolean
          description: Whether the general query log is enabled.
        log_level:
          type: string
          description: The current log verbosity level (debug, info, warn, error).
        ddl_slow_threshold:
          type: integer
          description: The threshold in milliseconds for loggin

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tidb/refs/heads/main/openapi/tidb-http-api-openapi.yml