> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API リファレンス

> ダッシュボード、アラート、ログソースをプログラムから管理するための ClickStack API リファレンス

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

ClickStack では、ダッシュボード、アラート、データソースをプログラムで管理するための REST API を提供しています。この API は **Managed ClickStack** (ClickHouse Cloud) と **ClickStack Open Source** の両方のデプロイで利用できますが、エンドポイントと認証方式は両者で異なります。

<div id="api-docs">
  ## API リファレンス
</div>

<Tabs>
  <Tab title="Managed ClickStack">
    Managed ClickStack では、API には **ClickHouse Cloud API** 経由でアクセスします。ClickStack のエンドポイントは、[Cloud API 仕様](/ja/api-reference/organization/get-list-of-available-organizations#tag/ClickStack)で利用できます。

    利用可能なエンドポイントは次のとおりです。

    | リソース        | 操作                       |
    | ----------- | ------------------------ |
    | **ダッシュボード** | ダッシュボードの作成、一覧表示、取得、更新、削除 |
    | **アラート**    | アラートの作成、一覧表示、取得、更新、削除    |
    | **SOURCES** | データソースの一覧表示              |
  </Tab>

  <Tab title="Open Source ClickStack">
    Open Source ClickStack では、完全な 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)

    利用可能なエンドポイントは次のとおりです。

    | リソース         | 操作                       |
    | ------------ | ------------------------ |
    | **ダッシュボード**  | ダッシュボードの作成、一覧表示、取得、更新、削除 |
    | **アラート**     | アラートの作成、一覧表示、取得、更新、削除    |
    | **チャート**     | 時系列データをクエリ (POST のみ)     |
    | **SOURCES**  | データソースの一覧表示              |
    | **Webhooks** | Webhooks の一覧表示           |
  </Tab>
</Tabs>

<div id="authentication">
  ## 認証
</div>

<Tabs>
  <Tab title="Managed ClickStack">
    Managed ClickStack では、[HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) による認証に **ClickHouse Cloud API key** を使用します。API key の作成と管理については、[API key の管理](/ja/products/cloud/features/admin-features/api/openapi) を参照してください。

    HTTP Basic Authentication を使用して、key ID と secret を指定します。

    ```bash theme={null}
    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 で HyperDX を開きます (例: [http://localhost:8080](http://localhost:8080))
    2. 必要に応じてアカウントを作成するか、ログインします
    3. **Team Settings → API Keys** に移動します
    4. **Personal API Access Key** をコピーします

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/api-key-personal.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=1c0b8af986f7f9c1480802fed946be27" alt="ClickStack API Key" width="3798" height="1938" data-path="images/clickstack/api-key-personal.png" />

    <Note>
      これは Team Settings にある **インジェスト API key** とは異なります。インジェスト API key は、OpenTelemetry collector に送信されるテレメトリーデータの認証に使用されます。
    </Note>

    API server はデフォルトでポート `8000` で動作します (ポート `8080` で動作する UI とは別です) 。all-in-one Docker image を使用する場合は、このポートを明示的にマッピングしてください。

    ```bash theme={null}
    docker run -p 8080:8080 -p 8000:8000 -p 4317:4317 -p 4318:4318 docker.hyperdx.io/hyperdx/hyperdx-all-in-one
    ```

    `Authorization` header に key を含めます。

    ```bash theme={null}
    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 theme={null}
    https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/<resource>
    ```

    **Organization ID** は、ClickHouse Cloudコンソールの **Organization → Organization details** で確認できます。**Service ID** は、サービスの URL またはサービス詳細ページに表示されます。

    ### 例: ダッシュボードを一覧表示する

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

    ### 例: アラートを作成する

    ```bash theme={null}
    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 theme={null}
    http://<YOUR_HYPERDX_HOST>:8000/api/v2/<resource>
    ```

    たとえば、デフォルトのローカルデプロイメントでは次のようになります。

    ```bash theme={null}
    http://localhost:8000/api/v2/dashboards
    ```

    ### 例: ダッシュボードを一覧表示する

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

    ### 例: アラートを作成する

    ```bash theme={null}
    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 theme={null}
    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>