openapi: 3.1.0
info:
  title: TiDB Cloud API Keys Integrations 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: Integrations
  description: Operations for managing third-party integrations with TiDB Cloud clusters.
paths:
  /clusters/{clusterId}/integrations:
    get:
      operationId: listIntegrations
      summary: List integrations
      description: Returns all third-party integrations configured for a specific TiDB Cloud Dedicated cluster. Supported integrations include Datadog, Prometheus, and other observability platforms.
      tags:
      - Integrations
      parameters:
      - $ref: '#/components/parameters/clusterId'
      responses:
        '200':
          description: List of integrations retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListIntegrationsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createIntegration
      summary: Create an integration
      description: Configures a new third-party integration for a specific TiDB Cloud Dedicated cluster. The integration type and credentials must be specified in the request body. Once created, TiDB Cloud will begin sending metrics and logs to the configured integration endpoint.
      tags:
      - Integrations
      parameters:
      - $ref: '#/components/parameters/clusterId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIntegrationRequest'
      responses:
        '200':
          description: Integration created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    clusterId:
      name: clusterId
      in: path
      description: The unique identifier of the TiDB Cloud Dedicated cluster.
      required: true
      schema:
        type: string
  schemas:
    Integration:
      type: object
      description: A third-party monitoring or observability integration for a cluster.
      properties:
        id:
          type: string
          description: The unique identifier of the integration.
        integrationType:
          type: string
          description: The type of integration (DATADOG, PROMETHEUS, etc.).
        active:
          type: boolean
          description: Whether the integration is currently active.
    ErrorResponse:
      type: object
      description: Standard error response returned when an API request fails.
      properties:
        code:
          type: integer
          description: The HTTP status code of the error.
        status:
          type: string
          description: The error status string.
        error:
          type: string
          description: A machine-readable error code identifier.
        msgPrefix:
          type: string
          description: A human-readable error message describing the failure.
    CreateIntegrationRequest:
      type: object
      description: Request body for creating a new cluster integration.
      required:
      - integrationType
      properties:
        integrationType:
          type: string
          description: The type of integration to create.
        config:
          type: object
          description: Integration-specific configuration properties such as API keys and region.
          additionalProperties: true
    ListIntegrationsResponse:
      type: object
      description: List of integrations for a cluster.
      properties:
        integrations:
          type: array
          description: The list of integration objects.
          items:
            $ref: '#/components/schemas/Integration'
  responses:
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication failed. Check your API key credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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/