API reference

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/observability/clickstack/api-reference.md)

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 "Direct link to API reference documentation")

- Managed ClickStack- Open Source ClickStack

For Managed ClickStack, the API is accessed through the **ClickHouse Cloud API**. The ClickStack endpoints are available in the [Cloud API specification](https://clickhouse.com/docs/cloud/manage/api/swagger#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 | | | | | | | |

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

## Authentication[​](#authentication "Direct link to Authentication")

- Managed ClickStack- Open Source 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](/docs/cloud/manage/openapi).

Include the key ID and secret using HTTP Basic Authentication:

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

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

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.

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:

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

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

## Base URL and request format[​](#base-url "Direct link to Base URL and request format")

- Managed ClickStack- Open Source ClickStack

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

```
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 "Direct link to Example: List dashboards")

```
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 "Direct link to Example: Create an alert")

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

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

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

For example, with a default local deployment:

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

### Example: List dashboards[​](#list-dashboards-oss "Direct link to Example: List dashboards")

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

### Example: Create an alert[​](#create-alert-oss "Direct link to Example: Create an alert")

```
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 "Direct link to Example: Query chart series data")

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

- [API reference documentation](#api-docs)- [Authentication](#authentication)- [Base URL and request format](#base-url)
      - [Example: List dashboards](#list-dashboards-managed)- [Example: Create an alert](#create-alert-managed)- [Example: List dashboards](#list-dashboards-oss)- [Example: Create an alert](#create-alert-oss)- [Example: Query chart series data](#query-series-data)

Was this page helpful?