Skip to content

api-reference.mdx

Latest commit

 

History

History
210 lines (159 loc) · 6.35 KB

api-reference.mdx

File metadata and controls

210 lines (159 loc) · 6.35 KB
Raw
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}

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

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:

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}

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

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

ClickStack API 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 {#base-url}

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}

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}

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}

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

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

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}

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