API 参考文档

ClickStack 提供 REST API，可用于以编程方式管理仪表盘、告警和数据源。该 API 同时适用于 托管 ClickStack (ClickHouse Cloud) 和 ClickStack 开源 部署，不过两者的端点和身份验证机制有所不同。

托管 ClickStack
开源 ClickStack

对于托管 ClickStack，需通过 ClickHouse Cloud API 访问 API。ClickStack 的端点可在 Cloud API 规范中查看。以下端点可用：

资源	操作
仪表盘	创建、列出、获取、更新和删除仪表盘
告警	创建、列出、获取、更新和删除告警
数据源	列出数据源

对于开源 ClickStack，完整的 API 规范由 HyperDX 仓库维护，可交互式查看或下载为 OpenAPI 规范：

以下端点可用：

资源	操作
仪表盘	创建、列出、获取、更新和删除仪表盘
告警	创建、列出、获取、更新和删除告警
图表	查询时间序列数据 (仅支持 POST)
数据源	列出数据源
Webhooks	列出 Webhooks

身份验证

托管 ClickStack
开源 ClickStack

托管 ClickStack 通过 HTTP Basic Authentication 使用 ClickHouse Cloud API key 进行身份验证。要创建和管理 API key，请参阅管理 API key。使用 HTTP Basic Authentication 时，需提供 key ID 和 secret：

export KEY_ID=<your_key_id>
export KEY_SECRET=<your_key_secret>

curl --user $KEY_ID:$KEY_SECRET \
  https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/dashboards

开源 ClickStack 使用 Personal API Access Key 作为 Bearer token 进行身份验证。要获取 API key：

在你的 ClickStack URL 打开 HyperDX (例如 http://localhost:8080)
创建账户，或在需要时登录
导航到 Team Settings → API Keys
复制你的 Personal API Access Key

这与 Team Settings 中的 摄取 API key 不同，后者用于对发送到 OpenTelemetry Collector 的遥测数据进行身份验证。

API 服务器默认运行在 8000 端口 (与使用 8080 端口的 UI 分开) 。使用 all-in-one Docker 镜像时，请确保显式映射此端口：

docker run -p 8080:8080 -p 8000:8000 -p 4317:4317 -p 4318:4318 docker.hyperdx.io/hyperdx/hyperdx-all-in-one

在 Authorization 请求头中包含该 key：

curl -H "Authorization: Bearer <YOUR_API_KEY>" \
  http://localhost:8000/api/v2/dashboards

Base URL 和请求格式

托管 ClickStack
开源 ClickStack

所有托管 ClickStack API 请求都会发送到 ClickHouse Cloud API：

https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/<resource>

你可以在 ClickHouse Cloud 控制台的 Organization → Organization details 中找到 Organization ID。Service ID 可在服务 URL 或服务详情页面中查看。

示例：列出仪表盘

curl --user $KEY_ID:$KEY_SECRET \
  https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/dashboards

示例：创建告警

curl -X POST --user $KEY_ID:$KEY_SECRET \
  -H "Content-Type: application/json" \
  -d '{
    "dashboardId": "<DASHBOARD_ID>",
    "tileId": "<TILE_ID>",
    "threshold": 100,
    "interval": "1h",
    "source": "tile",
    "thresholdType": "above",
    "channel": {
      "type": "webhook",
      "webhookId": "<WEBHOOK_ID>"
    },
    "name": "Error Spike Alert",
    "message": "Error rate exceeded 100 in the last hour"
  }' \
  https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/alerts

所有开源 ClickStack API 请求都会发送到端口 8000 上的 HyperDX API 服务器：

http://<YOUR_HYPERDX_HOST>:8000/api/v2/<resource>

例如，在默认的本地部署中：

http://localhost:8000/api/v2/dashboards

示例：列出仪表盘

curl -H "Authorization: Bearer <YOUR_API_KEY>" \
  http://localhost:8000/api/v2/dashboards

示例：创建告警

curl -X POST \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "dashboardId": "<DASHBOARD_ID>",
    "tileId": "<TILE_ID>",
    "threshold": 100,
    "interval": "1h",
    "source": "tile",
    "thresholdType": "above",
    "channel": {
      "type": "webhook",
      "webhookId": "<WEBHOOK_ID>"
    },
    "name": "Error Spike Alert",
    "message": "Error rate exceeded 100 in the last hour"
  }' \
  http://localhost:8000/api/v2/alerts

示例：查询图表序列数据

curl -X POST \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": 1647014400000,
    "endTime": 1647100800000,
    "granularity": "1h",
    "series": [
      {
        "sourceId": "<SOURCE_ID>",
        "aggFn": "count",
        "where": "SeverityText:error",
        "groupBy": []
      }
    ]
  }' \
  http://localhost:8000/api/v2/charts/series