openapi: 3.1.0
info:
  title: TiDB Cloud API Keys Settings 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: Settings
  description: Endpoints for retrieving and modifying TiDB server runtime settings.
paths:
  /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.
components:
  schemas:
    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 logging slow DDL operations.
    UpdateSettingsRequest:
      type: object
      description: Request body for updating TiDB server runtime settings.
      properties:
        tidb_general_log:
          type: integer
          description: Set to 1 to enable general query logging, 0 to disable.
          enum:
          - 0
          - 1
        log_level:
          type: string
          description: The new log level (debug, info, warn, error, fatal).
          enum:
          - debug
          - info
          - warn
          - error
          - fatal
        ddl_slow_threshold:
          type: integer
          description: New DDL slow threshold in milliseconds.
  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/