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

# API reference

> ClickStack API reference for managing dashboards, alerts, and sources programmatically

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

ClickStack exposes a REST API for programmatically managing dashboards, alerts, and data sources. The API is available for both **Managed ClickStack** (ClickHouse Cloud) and **ClickStack Open Source** deployments, though the endpoints and authentication differ between the two.

<h2 id="api-docs">
  API reference documentation
</h2>

<Tabs>
  <Tab title="Managed ClickStack">
    For Managed ClickStack, the API is accessed through the **ClickHouse Cloud API**. The ClickStack endpoints are available in the [Cloud API specification](/api-reference/organization/get-list-of-available-organizations#tag/ClickStack).

    The following endpoints are available:

    | Resource       | Operations                                       |
    | -------------- | ------------------------------------------------ |
    | **Dashboards** | Create, list, get, update, and delete dashboards |
    | **Alerts**     | Create, list, get, update, and delete alerts     |
    | **Sources**    | List data sources                                |
  </Tab>

  <Tab title="Open Source ClickStack">
    For ClickStack Open Source, the full API specification is maintained in the [HyperDX repository](https://github.com/hyperdxio/hyperdx) and can be viewed interactively or downloaded as an OpenAPI spec:

    * [Interactive API reference](https://www.clickhouse.com/docs/clickstack/api-reference)
    * [Download OpenAPI spec (JSON)](https://raw.githubusercontent.com/hyperdxio/hyperdx/refs/heads/main/packages/api/openapi.json)

    The following endpoints are available:

    | Resource       | Operations                                       |
    | -------------- | ------------------------------------------------ |
    | **Dashboards** | Create, list, get, update, and delete dashboards |
    | **Alerts**     | Create, list, get, update, and delete alerts     |
    | **Charts**     | Query time series data (POST only)               |
    | **Sources**    | List data sources                                |
    | **Webhooks**   | List webhooks                                    |
  </Tab>
</Tabs>

<h2 id="authentication">
  Authentication
</h2>

<Tabs>
  <Tab title="Managed ClickStack">
    Managed ClickStack uses the **ClickHouse Cloud API key** for authentication via [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). To create and manage API keys, see [Managing API keys](/products/cloud/features/admin-features/api/openapi).

    Include the key ID and secret using HTTP Basic Authentication:

    ```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 uses a **Bearer token** for authentication via a **Personal API Access Key**.

    To obtain an API key:

    1. Open HyperDX at your ClickStack URL (e.g., [http://localhost:8080](http://localhost:8080))
    2. Create an account or log in if needed
    3. Navigate to **Team Settings → API Keys**
    4. Copy your **Personal API Access Key**

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-3a82795f/aRvsybqUpVR5ZXyi/images/clickstack/api-key-personal.png?fit=max&auto=format&n=aRvsybqUpVR5ZXyi&q=85&s=72cc1e86a82b0078bfafd1fb338ebfb4" alt="ClickStack API Key" width="3798" height="1938" data-path="images/clickstack/api-key-personal.png" />

    <Note>
      This is different from the **Ingestion API Key** found in Team Settings, which is used to authenticate telemetry data sent to the OpenTelemetry collector.
    </Note>

    The API server runs on port `8000` by default (separate from the UI on port `8080`). When using the all-in-one Docker image, ensure you map this port explicitly:

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

    Include the key in the `Authorization` header:

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

<h2 id="base-url">
  Base URL and request format
</h2>

<Tabs>
  <Tab title="Managed ClickStack">
    All Managed ClickStack API requests are sent to the ClickHouse Cloud API:

    ```bash theme={null}
    https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/<resource>
    ```

    You can find your **Organization ID** in the ClickHouse Cloud console under **Organization → Organization details**. Your **Service ID** is visible in the service URL or on the service details page.

    <h3 id="list-dashboards-managed">
      Example: List dashboards
    </h3>

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

    <h3 id="create-alert-managed">
      Example: Create an alert
    </h3>

    ```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">
    All Open Source ClickStack API requests are sent to the HyperDX API server on port `8000`:

    ```bash theme={null}
    http://<YOUR_HYPERDX_HOST>:8000/api/v2/<resource>
    ```

    For example, with a default local deployment:

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

    <h3 id="list-dashboards-oss">
      Example: List dashboards
    </h3>

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

    <h3 id="create-alert-oss">
      Example: Create an alert
    </h3>

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

    <h3 id="query-series-data">
      Example: Query chart series data
    </h3>

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