Referencia de la API

Referencia de la API de ClickStack para gestionar dashboard, alertas y fuentes de datos de forma programática

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

Managed ClickStack

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 especificación de la API de Cloud.

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

Open Source ClickStack

Para Open Source ClickStack, 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:

• Referencia interactiva de la API
• Descargar la especificación OpenAPI (JSON)

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

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

Open Source ClickStack

ClickStack Open Source usa un token Bearer para la autenticación mediante una Personal API Access Key.

Para obtener una API key:

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

Esta es distinta de la API key de ingesta que se encuentra en Team Settings y se usa para autenticar los datos de telemetría enviados al collector de OpenTelemetry.

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

Managed ClickStack

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

Open Source ClickStack

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