Set up docs MCPClickStack는 대시보드, 알림, 데이터 소스를 프로그래밍 방식으로 관리할 수 있도록 REST API를 제공합니다. 이 API는 Managed ClickStack(ClickHouse Cloud)과 ClickStack Open Source 배포 모두에서 사용할 수 있지만, 두 환경에서는 엔드포인트와 인증 방식이 서로 다릅니다.
API 참조 문서
Managed ClickStack에서는 ClickHouse Cloud API를 통해 API를 사용합니다. ClickStack 엔드포인트는 Cloud API 참조에서 확인할 수 있습니다.
다음 엔드포인트를 사용할 수 있습니다:
| 리소스 | 작업 |
|---|---|
| Dashboards | 대시보드 생성, 목록 조회, 조회, 업데이트, 삭제 |
| Alerts | 알림 생성, 목록 조회, 조회, 업데이트, 삭제 |
| Sources | 데이터 소스 목록 조회 |
ClickStack Open Source의 전체 API 사양은 HyperDX 리포지토리에서 관리되며, 대화형으로 확인하거나 OpenAPI 사양으로 다운로드할 수 있습니다:
다음 엔드포인트를 사용할 수 있습니다:
| 리소스 | 작업 |
|---|---|
| Dashboards | 대시보드 생성, 목록 조회, 조회, 업데이트, 삭제 |
| Alerts | 알림 생성, 목록 조회, 조회, 업데이트, 삭제 |
| Charts | 시계열 데이터 쿼리(POST만 지원) |
| Sources | 데이터 소스 목록 조회 |
| Webhooks | 웹훅 목록 조회 |
인증
Managed ClickStack에서는 HTTP 기본 인증을 통해 ClickHouse Cloud API key를 사용해 인증합니다. API key를 생성하고 관리하는 방법은 API key 관리를 참조하십시오.
HTTP 기본 인증을 사용해 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/dashboardsClickStack Open Source는 Personal API Access Key를 사용하는 Bearer token 방식으로 인증합니다.
API key를 발급받으려면 다음 단계를 수행하십시오.
- ClickStack URL(예: http://localhost:8080)에서 HyperDX를 엽니다
- 필요한 경우 계정을 만들거나 로그인합니다
- Team Settings → API Keys로 이동합니다
- Personal API Access Key를 복사합니다
API server는 기본적으로 8000 포트에서 실행됩니다(8080 포트에서 실행되는 UI와는 별도). all-in-one Docker image를 사용하는 경우 이 포트를 명시적으로 매핑하십시오.
docker run -p 8080:8080 -p 8000:8000 -p 4317:4317 -p 4318:4318 docker.hyperdx.io/hyperdx/hyperdx-all-in-one키를 Authorization 헤더에 포함하십시오:
curl -H "Authorization: Bearer <YOUR_API_KEY>" \
http://localhost:8000/api/v2/dashboards기준 URL 및 요청 형식
모든 Managed ClickStack API 요청은 ClickHouse Cloud API로 전송됩니다.
https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/<resource>조직 ID는 ClickHouse Cloud 콘솔의 Organization → Organization details에서 확인할 수 있습니다. 서비스 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모든 Open Source 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