ClickHouse/docs/clickstack/api-reference.mdx

---
slug: /use-cases/observability/clickstack/api-reference
title: 'API reference'
description: 'ClickStack API reference for managing dashboards, alerts, and sources programmatically'
doc_type: 'guide'
keywords: ['ClickStack', 'observability', 'API', 'REST API', 'dashboards', 'alerts', 'HyperDX']
---

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

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.

## API reference documentation {#api-docs}

<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 reference](/products/cloud/api-reference/clickstack/click-stack-list-dashboards).

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>

## Authentication {#authentication}

<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
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)
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="/images/clickstack/api-key-personal.webp" alt="ClickStack API Key"/>

<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
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
curl -H "Authorization: Bearer <YOUR_API_KEY>" \
  http://localhost:8000/api/v2/dashboards
```

</Tab>
</Tabs>

## Base URL and request format {#base-url}

<Tabs>
<Tab title="Managed ClickStack">

All Managed ClickStack API requests are sent to the ClickHouse Cloud API:

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

### Example: List dashboards {#list-dashboards-managed}

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

### Example: Create an alert {#create-alert-managed}

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

All Open Source ClickStack API requests are sent to the HyperDX API server on port `8000`:

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

For example, with a default local deployment:

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

### Example: List dashboards {#list-dashboards-oss}

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

### Example: Create an alert {#create-alert-oss}

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

### Example: Query chart series data {#query-series-data}

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