ClickHouse/docs/ko/clickstack/api-reference.mdx

---
slug: /use-cases/observability/clickstack/api-reference
title: 'API 참조'
description: '대시보드, 알림, 소스를 프로그래밍 방식으로 관리하는 ClickStack API 참조'
doc_type: 'guide'
keywords: ['ClickStack', '관측성', 'API', 'REST API', '대시보드', '알림', 'HyperDX']
---

import { Image } from "/snippets/ko/components/Image.jsx";

ClickStack는 대시보드, 알림, 데이터 소스를 프로그래밍 방식으로 관리할 수 있도록 REST API를 제공합니다. 이 API는 **Managed ClickStack**(ClickHouse Cloud)과 **ClickStack Open Source** 배포 모두에서 사용할 수 있지만, 두 환경에서는 엔드포인트와 인증 방식이 서로 다릅니다.

<div id="api-docs">
  ## API 참조 문서
</div>

<Tabs>
  <Tab title="Managed ClickStack">
    Managed ClickStack에서는 **ClickHouse Cloud API**를 통해 API를 사용합니다. ClickStack 엔드포인트는 [Cloud API 참조](/ko/products/cloud/api-reference/clickstack/click-stack-list-dashboards)에서 확인할 수 있습니다.

    다음 엔드포인트를 사용할 수 있습니다:

    | 리소스            | 작업                           |
    | -------------- | ---------------------------- |
    | **Dashboards** | 대시보드 생성, 목록 조회, 조회, 업데이트, 삭제 |
    | **Alerts**     | 알림 생성, 목록 조회, 조회, 업데이트, 삭제   |
    | **Sources**    | 데이터 소스 목록 조회                 |
  </Tab>

  <Tab title="ClickStack Open Source">
    ClickStack Open Source의 전체 API 사양은 [HyperDX 리포지토리](https://github.com/hyperdxio/hyperdx)에서 관리되며, 대화형으로 확인하거나 OpenAPI 사양으로 다운로드할 수 있습니다:

    * [대화형 API 참조](https://www.clickhouse.com/docs/clickstack/api-reference)
    * [OpenAPI 사양 다운로드(JSON)](https://raw.githubusercontent.com/hyperdxio/hyperdx/refs/heads/main/packages/api/openapi.json)

    다음 엔드포인트를 사용할 수 있습니다:

    | 리소스            | 작업                           |
    | -------------- | ---------------------------- |
    | **Dashboards** | 대시보드 생성, 목록 조회, 조회, 업데이트, 삭제 |
    | **Alerts**     | 알림 생성, 목록 조회, 조회, 업데이트, 삭제   |
    | **Charts**     | 시계열 데이터 쿼리(POST만 지원)         |
    | **Sources**    | 데이터 소스 목록 조회                 |
    | **Webhooks**   | 웹훅 목록 조회                     |
  </Tab>
</Tabs>

<div id="authentication">
  ## 인증
</div>

<Tabs>
  <Tab title="Managed ClickStack">
    Managed ClickStack에서는 [HTTP 기본 인증](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)을 통해 **ClickHouse Cloud API key**를 사용해 인증합니다. API key를 생성하고 관리하는 방법은 [API key 관리](/ko/products/cloud/features/admin-features/api/openapi)를 참조하십시오.

    HTTP 기본 인증을 사용해 key ID와 secret을 포함하십시오:

    ```bash
    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
    ```
  </Tab>

  <Tab title="Open Source ClickStack">
    ClickStack Open Source는 **Personal API Access Key**를 사용하는 **Bearer token** 방식으로 인증합니다.

    API key를 발급받으려면 다음 단계를 수행하십시오.

    1. ClickStack URL(예: http://localhost:8080)에서 HyperDX를 엽니다
    2. 필요한 경우 계정을 만들거나 로그인합니다
    3. **Team Settings → API Keys**로 이동합니다
    4. **Personal API Access Key**를 복사합니다

    <Image img="/images/clickstack/api-key-personal.webp" alt="ClickStack API Key" />

    <Note>
      이 키는 Team Settings에서 확인할 수 있는 **수집 API key**와 다릅니다. 수집 API key는 OpenTelemetry collector로 전송되는 텔레메트리 데이터의 인증에 사용됩니다.
    </Note>

    API server는 기본적으로 `8000` 포트에서 실행됩니다(`8080` 포트에서 실행되는 UI와는 별도). all-in-one Docker image를 사용하는 경우 이 포트를 명시적으로 매핑하십시오.

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

    키를 `Authorization` 헤더에 포함하십시오:

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

<div id="base-url">
  ## 기준 URL 및 요청 형식
</div>

<Tabs>
  <Tab title="Managed ClickStack">
    모든 Managed ClickStack API 요청은 ClickHouse Cloud API로 전송됩니다.

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

    **조직 ID**는 ClickHouse Cloud 콘솔의 **Organization → Organization details**에서 확인할 수 있습니다. **서비스 ID**는 서비스 URL 또는 서비스 세부 정보 페이지에 표시됩니다.

    ### 예시: 대시보드 목록 조회

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

    ### 예시: 알림 생성

    ```bash
    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
    ```
  </Tab>

  <Tab title="Open Source ClickStack">
    모든 Open Source ClickStack API 요청은 포트 `8000`에서 실행되는 HyperDX API 서버로 전송됩니다.

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

    예를 들어, 기본 로컬 배포에서는 다음과 같습니다.

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

    ### 예시: 대시보드 목록 조회

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

    ### 예시: 알림 생성

    ```bash
    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
    ```

    ### 예시: 차트 시리즈 데이터 쿼리

    ```bash
    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
    ```
  </Tab>
</Tabs>