API reference

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

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

Managed ClickStack

For Managed ClickStack, the API is accessed through the ClickHouse Cloud API. The ClickStack endpoints are available in the Cloud API specification.

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

Open Source ClickStack

For ClickStack Open Source, the full API specification is maintained in the HyperDX repository and can be viewed interactively or downloaded as an OpenAPI spec:

• Interactive API reference
• Download OpenAPI spec (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

Managed ClickStack

Managed ClickStack uses the ClickHouse Cloud API key for authentication via HTTP Basic Authentication. To create and manage API keys, see Managing API keys.

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

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

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

Managed 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

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

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

Open Source ClickStack

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

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

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

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