PingCAP Integration API

openapi: 3.2.0
info:
  title: TiDB Cloud Dedicated Integration API
  description: '*TiDB Cloud API is in beta.*


    This API manages TiDB Cloud Dedicated clusters.'
  version: v1beta1
servers:
- url: https://dedicated.tidbapi.com/v1beta1
tags:
- name: Integration
  description: List integrations, create an integration, and delete an integration.
paths:
  /clusters/{clusterId}/integrations:
    get:
      summary: List integrations
      description: Lists all integrations configured for a cluster, including their current runtime status.
      operationId: IntegrationService_ListIntegrations
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/openapiv1beta1ListIntegrationsResp'
        '400':
          description: A request field is invalid.
          content:
            application/json:
              schema:
                example:
                  code: 400
                  message: 'Invalid request: missing or invalid field'
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        '401':
          description: The API key cannot be authenticated.
          content:
            application/json:
              schema:
                example:
                  code: 401
                  message: The API key cannot be authenticated.
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        '403':
          description: The API key does not have permission to access the resource.
          content:
            application/json:
              schema:
                example:
                  code: 403
                  message: The API key does not have permission to access the resource.
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        '429':
          description: You have exceeded the rate limit.
          content:
            application/json:
              schema:
                example:
                  code: 429
                  message: You have exceeded the rate limit.
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                example:
                  code: 500
                  message: Internal server error
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: clusterId
        description: The ID of the cluster to list integrations for.
        in: path
        required: true
        schema:
          type: string
          format: uint64
      tags:
      - Integration
      x-codeSamples:
      - label: curl
        lang: bash
        source: "curl -X GET \"https://dedicated.tidbapi.com/v1beta1/clusters/123/integrations\" \\\n  --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  -H \"Accept: application/json\""
    post:
      summary: Create an integration
      description: Creates a new external metrics integration for the specified cluster. Supported integrations include Datadog, New Relic, and Prometheus.
      operationId: IntegrationService_CreateIntegration
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/openapiv1beta1IntegrationStatusResp'
        '400':
          description: A request field is invalid.
          content:
            application/json:
              schema:
                example:
                  code: 400
                  message: 'Invalid request: missing or invalid field'
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        '401':
          description: The API key cannot be authenticated.
          content:
            application/json:
              schema:
                example:
                  code: 401
                  message: The API key cannot be authenticated.
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        '403':
          description: The API key does not have permission to access the resource.
          content:
            application/json:
              schema:
                example:
                  code: 403
                  message: The API key does not have permission to access the resource.
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        '429':
          description: You have exceeded the rate limit.
          content:
            application/json:
              schema:
                example:
                  code: 429
                  message: You have exceeded the rate limit.
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                example:
                  code: 500
                  message: Internal server error
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: clusterId
        description: The ID of the target cluster where the integration will be created.
        in: path
        required: true
        schema:
          type: string
          format: uint64
      tags:
      - Integration
      x-codeSamples:
      - label: curl
        lang: bash
        source: "curl -X POST \"https://dedicated.tidbapi.com/v1beta1/clusters/123/integrations\" \\\n  --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"type\": \"DATADOG\",\n    \"datadog\": {\n      \"api_key\": \"<DATADOG_API_KEY>\",\n      \"site\": \"US1\"\n    }\n  }'"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                type: DATADOG
                datadog:
                  api_key: <DATADOG_API_KEY>
                  site: US1
              properties:
                type:
                  description: 'The service provider for the integration. Must be one of the supported values: `"DATADOG"`, `"NEWRELIC"`, or `"PROMETHEUS"`.'
                  allOf:
                  - $ref: '#/components/schemas/openapiv1beta1IntegrationType'
                datadog:
                  description: The configuration for the Datadog integration. This is required when `type` is `"DATADOG"`.
                  allOf:
                  - $ref: '#/components/schemas/v1beta1CreateDatadogIntegrationRequest'
                newrelic:
                  description: The configuration for the New Relic integration. This is required when `type` is `"NEWRELIC"`.
                  allOf:
                  - $ref: '#/components/schemas/v1beta1CreateNewrelicIntegrationRequest'
                prometheus:
                  description: The configuration for the Prometheus integration. This is required when `type` is `"PROMETHEUS"`.
                  allOf:
                  - $ref: '#/components/schemas/v1beta1CreatePrometheusMetricsKeyRequest'
        required: true
  /clusters/{clusterId}/integrations/{id}:
    delete:
      summary: Delete an integration
      description: Removes an integration from the cluster.
      operationId: IntegrationService_DeleteIntegration
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: A request field is invalid.
          content:
            application/json:
              schema:
                example:
                  code: 400
                  message: 'Invalid request: missing or invalid field'
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        '401':
          description: The API key cannot be authenticated.
          content:
            application/json:
              schema:
                example:
                  code: 401
                  message: The API key cannot be authenticated.
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        '403':
          description: The API key does not have permission to access the resource.
          content:
            application/json:
              schema:
                example:
                  code: 403
                  message: The API key does not have permission to access the resource.
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        '429':
          description: You have exceeded the rate limit.
          content:
            application/json:
              schema:
                example:
                  code: 429
                  message: You have exceeded the rate limit.
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                example:
                  code: 500
                  message: Internal server error
                  details: []
                allOf:
                - $ref: '#/components/schemas/rpcStatus'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: clusterId
        description: The ID of the cluster from which to delete the integration.
        in: path
        required: true
        schema:
          type: string
          format: uint64
      - name: id
        description: The ID of the integration to delete.
        in: path
        required: true
        schema:
          type: string
          format: uint64
      tags:
      - Integration
      x-codeSamples:
      - label: curl
        lang: bash
        source: "curl -X DELETE \"https://dedicated.tidbapi.com/v1beta1/clusters/123/integrations/456\" \\\n  --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  -H \"Accept: application/json\""
components:
  schemas:
    v1beta1CreateDatadogIntegrationRequest:
      type: object
      example:
        api_key: <DATADOG_API_KEY>
        site: US1
      properties:
        apiKey:
          type: string
          description: The Datadog API key used to authenticate your integration. This field is write-only and will be masked in all responses.
        site:
          description: The Datadog site region where your cluster metrics are sent.
          allOf:
          - $ref: '#/components/schemas/openapiv1beta1DatadogSite'
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
    openapiv1beta1NewrelicSite:
      type: string
      enum:
      - US_OTLP
      - EU_OTLP
    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    }"
    openapiv1beta1ListIntegrationsResp:
      type: object
      example:
        items:
        - id: 103
          type: DATADOG
          datadog:
            state: ACTIVE
            site: US1
            masked_api_key: '****3086'
          create_time: '2025-10-23T12:34:56Z'
          update_time: '2025-10-24T08:21:00Z'
          creator: admin@example.com
        total: 1
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/openapiv1beta1IntegrationStatusResp'
          description: The list of integrations configured for the cluster.
        total:
          type: integer
          format: int32
          description: The total number of integrations configured for the cluster.
    v1beta1DatadogIntegrationStatusResp:
      type: object
      example:
        state: ACTIVE
        status_reason: ''
        site: US1
        site_url: https://app.datadoghq.com
        dashboard_url: https://app.datadoghq.com/dashboard/example
        masked_api_key: '****3086'
      properties:
        state:
          description: The current state of the Datadog integration.
          allOf:
          - $ref: '#/components/schemas/v1beta1IntegrationState'
        statusReason:
          type: string
          description: A message describing the reason for an `ERROR` state. Empty when the integration is functioning normally.
        site:
          description: The Datadog site region where your cluster metrics are sent.
          allOf:
          - $ref: '#/components/schemas/openapiv1beta1DatadogSite'
        siteUrl:
          type: string
          description: The base URL of the Datadog site.
        dashboardUrl:
          type: string
          description: A link to view your cluster metrics in Datadog.
        maskedApiKey:
          type: string
          description: The API key used for the integration, which is partially masked.
    openapiv1beta1IntegrationStatusResp:
      type: object
      example:
        id: 103
        type: DATADOG
        datadog:
          state: ACTIVE
          status_reason: ''
          site: US1
          site_url: https://app.datadoghq.com
          dashboard_url: https://app.datadoghq.com/dashboard/example
          masked_api_key: '****3086'
        create_time: '2025-10-23T12:34:56Z'
        update_time: '2025-10-24T08:21:00Z'
        creator: admin@example.com
      properties:
        id:
          type: string
          format: uint64
          description: The unique identifier of the integration.
        type:
          description: The service provider for the integration.
          allOf:
          - $ref: '#/components/schemas/openapiv1beta1IntegrationType'
        datadog:
          description: The configuration and status details for the Datadog integration.
          allOf:
          - $ref: '#/components/schemas/v1beta1DatadogIntegrationStatusResp'
        newrelic:
          description: The configuration and status details for the New Relic integration.
          allOf:
          - $ref: '#/components/schemas/v1beta1NewrelicIntegrationStatusResp'
        prometheus:
          description: The configuration and status details for the Prometheus integration.
          allOf:
          - $ref: '#/components/schemas/openapiv1beta1CreateMetricsKeyResp'
        createTime:
          type: string
          format: date-time
          description: The timestamp when the integration was created, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        updateTime:
          type: string
          format: date-time
          description: The timestamp when the integration was last updated, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        creator:
          type: string
          description: The email address or system identifier of the user who created the integration.
    openapiv1beta1CreateMetricsKeyResp:
      type: object
      example:
        key: <PROMETHEUS_READ_KEY>
        query_endpoint: https://prom.example.com/api/v1/query
      properties:
        key:
          type: string
          description: The generated read-only API key for authenticating Prometheus queries.
        queryEndpoint:
          type: string
          description: The Prometheus-compatible HTTP endpoint for querying your cluster metrics.
    v1beta1NewrelicIntegrationStatusResp:
      type: object
      example:
        state: ACTIVE
        status_reason: ''
        site: US_OTLP
        site_url: https://one.newrelic.com
        dashboard_url: https://one.newrelic.com/dashboard/example
        masked_api_key: '****abcd'
      properties:
        state:
          description: The current state of the New Relic integration.
          allOf:
          - $ref: '#/components/schemas/v1beta1IntegrationState'
        statusReason:
          type: string
          description: A message describing the reason for an `ERROR` state. Empty when the integration is functioning normally.
        site:
          description: The New Relic ingestion site to use for metrics collection.
          allOf:
          - $ref: '#/components/schemas/openapiv1beta1NewrelicSite'
        siteUrl:
          type: string
          description: The base URL of the New Relic site.
        dashboardUrl:
          type: string
          description: A link to view your cluster metrics in New Relic.
        maskedApiKey:
          type: string
          description: The API key used for the integration, which is partially masked.
    v1beta1CreatePrometheusMetricsKeyRequest:
      type: object
      example: {}
    v1beta1CreateNewrelicIntegrationRequest:
      type: object
      example:
        api_key: <NEWRELIC_API_KEY>
        site: US_OTLP
      properties:
        apiKey:
          type: string
          description: The New Relic ingestion key used to connect your cluster to New Relic. This field is write-only and will be masked in all responses.
        site:
          description: The New Relic ingestion site where your cluster metrics are sent.
          allOf:
          - $ref: '#/components/schemas/openapiv1beta1NewrelicSite'
    v1beta1IntegrationState:
      type: string
      enum:
      - NONE
      - ACTIVE
      - ERROR
    openapiv1beta1IntegrationType:
      type: string
      enum:
      - DATADOG
      - NEWRELIC
      - PROMETHEUS
    openapiv1beta1DatadogSite:
      type: string
      enum:
      - US1
      - US3
      - US5
      - EU1
      - US1_FED
      - AP1
      - AP2
x-tagGroups:
- name: Endpoints
  tags:
  - Cluster
  - Region
  - Private Endpoint Connection
  - Import
  - Integration
  - Changefeed