{
  "swagger": "2.0",
  "info": {
    "title": "TiDB Cloud Integration API",
    "description": "APIs to create, list and delete external metrics integrations (Datadog, New Relic, Prometheus) for TiDB Cloud clusters.",
    "version": "v1beta1"
  },
  "tags": [
    {
      "name": "IntegrationService"
    }
  ],
  "host": "dedicated.tidbapi.com",
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/v1beta1/clusters/{clusterId}/integrations": {
      "get": {
        "summary": "List integrations",
        "description": "Return all integrations configured for a cluster, along with their runtime status.",
        "operationId": "IntegrationService_ListIntegrations",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1beta1ListIntegrationsResp"
            }
          },
          "400": {
            "description": "A request field is invalid.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 400,
                "message": "Invalid request: missing or invalid field",
                "details": []
              }
            }
          },
          "401": {
            "description": "The API key cannot be authenticated.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 401,
                "message": "The API key cannot be authenticated.",
                "details": []
              }
            }
          },
          "403": {
            "description": "The API key does not have permission to access the resource.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 403,
                "message": "The API key does not have permission to access the resource.",
                "details": []
              }
            }
          },
          "429": {
            "description": "You have exceeded the rate limit.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 429,
                "message": "You have exceeded the rate limit.",
                "details": []
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 500,
                "message": "Internal server error",
                "details": []
              }
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "Cluster identifier used to filter integrations.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          }
        ],
        "tags": [
          "IntegrationService"
        ],
        "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": "Create a new external metrics integration (Datadog, New Relic or Prometheus) for the specified cluster.",
        "operationId": "IntegrationService_CreateIntegration",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1beta1IntegrationStatusResp"
            }
          },
          "400": {
            "description": "A request field is invalid.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 400,
                "message": "Invalid request: missing or invalid field",
                "details": []
              }
            }
          },
          "401": {
            "description": "The API key cannot be authenticated.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 401,
                "message": "The API key cannot be authenticated.",
                "details": []
              }
            }
          },
          "403": {
            "description": "The API key does not have permission to access the resource.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 403,
                "message": "The API key does not have permission to access the resource.",
                "details": []
              }
            }
          },
          "429": {
            "description": "You have exceeded the rate limit.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 429,
                "message": "You have exceeded the rate limit.",
                "details": []
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 500,
                "message": "Internal server error",
                "details": []
              }
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "The numeric TiDB Cloud cluster identifier. Specifies which cluster the integration applies to.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "example": {
                "type": "DATADOG",
                "datadog": {
                  "apiKey": "\u003cDATADOG_API_KEY\u003e",
                  "site": "US1"
                }
              },
              "properties": {
                "type": {
                  "description": "The type of integration to create. Must match one of the supported IntegrationType enum values (DATADOG, NEWRELIC, PROMETHEUS).",
                  "title": "IntegrationType",
                  "allOf": [
                    {
                      "$ref": "#/definitions/v1beta1IntegrationType"
                    }
                  ]
                },
                "datadog": {
                  "description": "Configuration for the Datadog integration.",
                  "title": "Datadog",
                  "allOf": [
                    {
                      "$ref": "#/definitions/v1beta1CreateDatadogIntegrationRequest"
                    }
                  ]
                },
                "newrelic": {
                  "description": "Configuration for the New Relic integration.",
                  "title": "NewRelic",
                  "allOf": [
                    {
                      "$ref": "#/definitions/v1beta1CreateNewrelicIntegrationRequest"
                    }
                  ]
                },
                "prometheus": {
                  "description": "Configuration for the Prometheus integration.",
                  "title": "Prometheus",
                  "allOf": [
                    {
                      "$ref": "#/definitions/v1beta1CreatePrometheusMetricsKeyRequest"
                    }
                  ]
                }
              }
            }
          }
        ],
        "tags": [
          "IntegrationService"
        ],
        "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      \"apiKey\": \"\u003cDATADOG_API_KEY\u003e\",\n      \"site\": \"US1\"\n    }\n  }'"
          }
        ]
      }
    },
    "/v1beta1/clusters/{clusterId}/integrations/{id}": {
      "delete": {
        "summary": "Delete an integration",
        "description": "Remove an integration identified by id from the given cluster.",
        "operationId": "IntegrationService_DeleteIntegration",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "type": "object",
              "properties": {}
            }
          },
          "400": {
            "description": "A request field is invalid.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 400,
                "message": "Invalid request: missing or invalid field",
                "details": []
              }
            }
          },
          "401": {
            "description": "The API key cannot be authenticated.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 401,
                "message": "The API key cannot be authenticated.",
                "details": []
              }
            }
          },
          "403": {
            "description": "The API key does not have permission to access the resource.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 403,
                "message": "The API key does not have permission to access the resource.",
                "details": []
              }
            }
          },
          "429": {
            "description": "You have exceeded the rate limit.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 429,
                "message": "You have exceeded the rate limit.",
                "details": []
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "schema": {
              "$ref": "#/definitions/rpcStatus",
              "example": {
                "code": 500,
                "message": "Internal server error",
                "details": []
              }
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "Cluster identifier related to the integration to be deleted.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          },
          {
            "name": "id",
            "description": "Identifier of the integration to delete.",
            "in": "path",
            "required": true,
            "type": "string",
            "format": "uint64"
          }
        ],
        "tags": [
          "IntegrationService"
        ],
        "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\""
          }
        ]
      }
    }
  },
  "definitions": {
    "protobufAny": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "string"
        }
      },
      "additionalProperties": {}
    },
    "rpcStatus": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/protobufAny"
          }
        }
      }
    },
    "v1beta1CreateDatadogIntegrationRequest": {
      "type": "object",
      "example": {
        "apiKey": "\u003cDATADOG_API_KEY\u003e",
        "site": "US1"
      },
      "properties": {
        "apiKey": {
          "type": "string",
          "description": "Datadog API key (write-only). The server will mask or not return the full key in list/status responses for security.",
          "title": "APIKey"
        },
        "site": {
          "description": "Datadog regional site where metrics will be sent (e.g., US1, EU1).",
          "title": "DatadogSite",
          "allOf": [
            {
              "$ref": "#/definitions/v1beta1DatadogSite"
            }
          ]
        }
      }
    },
    "v1beta1CreateMetricsKeyResp": {
      "type": "object",
      "example": {
        "key": "\u003cPROMETHEUS_READ_KEY\u003e",
        "queryEndpoint": "https://prom.example.com/api/v1/query"
      },
      "properties": {
        "key": {
          "type": "string",
          "description": "Generated Prometheus read key (sensitive). Provided when creating a new key.",
          "title": "Key"
        },
        "queryEndpoint": {
          "type": "string",
          "description": "Prometheus-compatible HTTP endpoint to query metrics using the provided key.",
          "title": "QueryEndpoint"
        }
      }
    },
    "v1beta1CreateNewrelicIntegrationRequest": {
      "type": "object",
      "example": {
        "apiKey": "\u003cNEWRELIC_API_KEY\u003e",
        "site": "US_OTLP"
      },
      "properties": {
        "apiKey": {
          "type": "string",
          "description": "New Relic ingestion key (write-only). The server will mask this value in responses.",
          "title": "APIKey"
        },
        "site": {
          "description": "New Relic ingestion site selection (e.g., US_OTLP, EU_OTLP).",
          "title": "NewRelicSite",
          "allOf": [
            {
              "$ref": "#/definitions/v1beta1NewrelicSite"
            }
          ]
        }
      }
    },
    "v1beta1CreatePrometheusMetricsKeyRequest": {
      "type": "object",
      "example": {}
    },
    "v1beta1DatadogIntegrationStatusResp": {
      "type": "object",
      "example": {
        "state": "ACTIVE",
        "statusReason": "",
        "site": "US1",
        "siteUrl": "https://app.datadoghq.com",
        "dashboardUrl": "https://app.datadoghq.com/dashboard/example",
        "maskedApiKey": "****3086"
      },
      "properties": {
        "state": {
          "description": "The current lifecycle state of the Datadog integration (NONE, ACTIVE, ERROR).",
          "title": "State",
          "allOf": [
            {
              "$ref": "#/definitions/v1beta1IntegrationState"
            }
          ]
        },
        "statusReason": {
          "type": "string",
          "description": "When state is ERROR, provides a human-readable explanation of the failure.",
          "title": "StatusReason"
        },
        "site": {
          "description": "Configured Datadog site for this integration.",
          "title": "DatadogSite",
          "allOf": [
            {
              "$ref": "#/definitions/v1beta1DatadogSite"
            }
          ]
        },
        "siteUrl": {
          "type": "string",
          "description": "The URL of the Datadog site configured for this integration.",
          "title": "SiteURL"
        },
        "dashboardUrl": {
          "type": "string",
          "description": "A URL to a recommended dashboard in Datadog for viewing cluster metrics.",
          "title": "DashboardURL"
        },
        "maskedApiKey": {
          "type": "string",
          "description": "Masked representation of the Datadog API key (for display only).",
          "title": "MaskedApiKey"
        }
      }
    },
    "v1beta1DatadogSite": {
      "type": "string",
      "enum": [
        "US1",
        "US3",
        "US5",
        "EU1",
        "US1_FED",
        "AP1",
        "AP2"
      ]
    },
    "v1beta1IntegrationState": {
      "type": "string",
      "enum": [
        "NONE",
        "ACTIVE",
        "ERROR"
      ]
    },
    "v1beta1IntegrationStatusResp": {
      "type": "object",
      "example": {
        "id": 103,
        "type": "DATADOG",
        "datadog": {
          "state": "ACTIVE",
          "statusReason": "",
          "site": "US1",
          "siteUrl": "https://app.datadoghq.com",
          "dashboardUrl": "https://app.datadoghq.com/dashboard/example",
          "maskedApiKey": "****3086"
        },
        "createTime": "2025-10-23T12:34:56Z",
        "updateTime": "2025-10-24T08:21:00Z",
        "creator": "admin@example.com"
      },
      "properties": {
        "id": {
          "type": "string",
          "format": "uint64",
          "description": "Unique identifier for the integration resource.",
          "title": "IntegrationID"
        },
        "type": {
          "description": "The type of integration.",
          "title": "IntegrationType",
          "allOf": [
            {
              "$ref": "#/definitions/v1beta1IntegrationType"
            }
          ]
        },
        "datadog": {
          "description": "Configuration for the Datadog integration.",
          "title": "Datadog",
          "allOf": [
            {
              "$ref": "#/definitions/v1beta1DatadogIntegrationStatusResp"
            }
          ]
        },
        "newrelic": {
          "description": "Configuration for the New Relic integration.",
          "title": "NewRelic",
          "allOf": [
            {
              "$ref": "#/definitions/v1beta1NewrelicIntegrationStatusResp"
            }
          ]
        },
        "prometheus": {
          "description": "Configuration for the Prometheus integration.",
          "title": "Prometheus",
          "allOf": [
            {
              "$ref": "#/definitions/v1beta1CreateMetricsKeyResp"
            }
          ]
        },
        "createTime": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp when the integration was created.",
          "title": "CreateTime"
        },
        "updateTime": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp when the integration was last updated.",
          "title": "UpdateTime"
        },
        "creator": {
          "type": "string",
          "description": "Identifier (username or system) of the actor who created the integration.",
          "title": "Creator"
        }
      }
    },
    "v1beta1IntegrationType": {
      "type": "string",
      "enum": [
        "DATADOG",
        "NEWRELIC",
        "PROMETHEUS"
      ]
    },
    "v1beta1ListIntegrationsResp": {
      "type": "object",
      "example": {
        "items": [
          {
            "id": 103,
            "type": "DATADOG",
            "datadog": {
              "state": "ACTIVE",
              "site": "US1",
              "maskedApiKey": "****3086"
            },
            "createTime": "2025-10-23T12:34:56Z",
            "updateTime": "2025-10-24T08:21:00Z",
            "creator": "admin@example.com"
          }
        ],
        "total": 1
      },
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/v1beta1IntegrationStatusResp"
          },
          "description": "Array of integration status objects associated with the cluster.",
          "title": "Items"
        },
        "total": {
          "type": "integer",
          "format": "int32",
          "description": "Total number of integrations for the cluster.",
          "title": "Total"
        }
      }
    },
    "v1beta1NewrelicIntegrationStatusResp": {
      "type": "object",
      "example": {
        "state": "ACTIVE",
        "statusReason": "",
        "site": "US_OTLP",
        "siteUrl": "https://one.newrelic.com",
        "dashboardUrl": "https://one.newrelic.com/dashboard/example",
        "maskedApiKey": "****abcd"
      },
      "properties": {
        "state": {
          "description": "Current lifecycle state of the New Relic integration.",
          "title": "State",
          "allOf": [
            {
              "$ref": "#/definitions/v1beta1IntegrationState"
            }
          ]
        },
        "statusReason": {
          "type": "string",
          "description": "Human-readable reason when the integration is in ERROR state.",
          "title": "StatusReason"
        },
        "site": {
          "description": "Configured New Relic ingestion site for this integration.",
          "title": "NewRelicSite",
          "allOf": [
            {
              "$ref": "#/definitions/v1beta1NewrelicSite"
            }
          ]
        },
        "siteUrl": {
          "type": "string",
          "description": "The New Relic site URL associated with this integration.",
          "title": "SiteURL"
        },
        "dashboardUrl": {
          "type": "string",
          "description": "Link to a recommended New Relic dashboard for the cluster.",
          "title": "DashboardURL"
        },
        "maskedApiKey": {
          "type": "string",
          "description": "Masked New Relic key returned for display; not the full secret.",
          "title": "MaskedApiKey"
        }
      }
    },
    "v1beta1NewrelicSite": {
      "type": "string",
      "enum": [
        "US_OTLP",
        "EU_OTLP"
      ]
    }
  }
}