Referencia de la API | ClickHouse Docs

ClickStack expone una API REST para gestionar de forma programática dashboard, alertas y fuentes de datos. La API está disponible tanto para las implementaciones de Managed ClickStack (ClickHouse Cloud) como para los despliegues de ClickStack Open Source, aunque los endpoints y la autenticación difieren entre ambos.

Documentación de referencia de la API

Para Managed ClickStack, se accede a la API a través de la ClickHouse Cloud API. Los endpoints de ClickStack están disponibles en la referencia de Cloud API.

Los siguientes endpoints están disponibles:

Recurso	Operaciones
Dashboards	Crear, listar, obtener, actualizar y eliminar dashboards
Alerts	Crear, listar, obtener, actualizar y eliminar alertas
Sources	Listar fuentes de datos

Para ClickStack Open Source, la especificación completa de la API se mantiene en el repositorio de HyperDX y puede consultarse de forma interactiva o descargarse como una especificación OpenAPI:

Los siguientes endpoints están disponibles:

Recurso	Operaciones
Dashboards	Crear, listar, obtener, actualizar y eliminar dashboards
Alerts	Crear, listar, obtener, actualizar y eliminar alertas
Charts	Consultar datos de series temporales (solo POST)
Sources	Listar fuentes de datos
Webhooks	Listar webhooks

Autenticación

Managed ClickStack usa la API key de ClickHouse Cloud para autenticarse mediante HTTP Basic Authentication. Para crear y administrar API keys, consulta Administrar API keys.

Incluye el ID de la clave y el secreto mediante 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 usa un token Bearer para la autenticación mediante una Personal API Access Key.

Para obtener una API key:

Abre HyperDX en la URL de tu ClickStack (por ejemplo, http://localhost:8080)
Crea una cuenta o inicia sesión si es necesario
Ve a Team Settings → API Keys
Copia tu Personal API Access Key

El servidor de la API se ejecuta en el puerto 8000 de forma predeterminada (separado de la UI en el puerto 8080). Si usas la imagen todo en uno de Docker, asegúrate de asignar este puerto explícitamente:

docker run -p 8080:8080 -p 8000:8000 -p 4317:4317 -p 4318:4318 docker.hyperdx.io/hyperdx/hyperdx-all-in-one

Incluye la clave en el encabezado Authorization:

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

URL base y formato de solicitud

Todas las solicitudes a la API de Managed ClickStack se envían a la ClickHouse Cloud API:

https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/<resource>

Puede encontrar su Organization ID en ClickHouse Cloud console, en Organization → Organization details. Su Service ID aparece en la URL del servicio o en la página de detalles del servicio.

Ejemplo: Listar dashboards

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

Ejemplo: Crear una alerta

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

Todas las solicitudes a la API de Open Source ClickStack se envían al servidor de la API de HyperDX en el puerto 8000:

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

Por ejemplo, con una implementación local predeterminada:

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

Ejemplo: Listar dashboards

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

Ejemplo: Crear una alerta

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

Ejemplo: Consultar datos de series de un gráfico

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