Référence API

Référence API ClickStack pour gérer les tableaux de bord, les alertes et les sources par programmation

ClickStack met à disposition une API REST pour gérer de façon programmatique les tableaux de bord, les alertes et les sources de données. L’API est disponible à la fois pour les déploiements Managed ClickStack (ClickHouse Cloud) et ClickStack Open Source, bien que les points de terminaison et l’authentification diffèrent entre les deux.

​

Documentation de référence de l’API

Managed ClickStack

Pour Managed ClickStack, l’API est accessible via la ClickHouse Cloud API. Les endpoints ClickStack sont disponibles dans la spécification de la Cloud API.

Les endpoints suivants sont disponibles :

Ressource	Opérations
Tableaux de bord	Créer, lister, récupérer, mettre à jour et supprimer des tableaux de bord
Alertes	Créer, lister, récupérer, mettre à jour et supprimer des alertes
Sources	Lister les sources de données

Open Source ClickStack

Pour ClickStack Open Source, la spécification complète de l’API est maintenue dans le dépôt HyperDX et peut être consultée de façon interactive ou téléchargée au format OpenAPI :

• Référence interactive de l’API
• Télécharger la spécification OpenAPI (JSON)

Les endpoints suivants sont disponibles :

Ressource	Opérations
Tableaux de bord	Créer, lister, récupérer, mettre à jour et supprimer des tableaux de bord
Alertes	Créer, lister, récupérer, mettre à jour et supprimer des alertes
Graphiques	Interroger des données de séries temporelles (POST uniquement)
Sources	Lister les sources de données
Webhooks	Lister les webhooks

​

Authentification

Managed ClickStack

Managed ClickStack utilise la clé API ClickHouse Cloud pour l’authentification via l’authentification HTTP Basic. Pour créer et gérer des clés API, consultez Gestion des clés API.

Incluez l’ID de la clé et le secret à l’aide de l’authentification HTTP Basic :

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 utilise un Bearer token pour l’authentification via une Personal API Access Key.

Pour obtenir une clé API :

1. Ouvrez HyperDX à l’URL de votre instance ClickStack (par exemple, http://localhost:8080)
2. Créez un compte ou connectez-vous si nécessaire
3. Accédez à Team Settings → API Keys
4. Copiez votre Personal API Access Key

Elle est différente de la clé API d’ingestion disponible dans Team Settings, qui sert à authentifier les données de télémétrie envoyées au collector OpenTelemetry.

Par défaut, le serveur API s’exécute sur le port 8000 (distinct de l’UI, qui utilise le port 8080). Si vous utilisez l’image Docker tout-en-un, veillez à mapper explicitement ce port :

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

Incluez la clé dans l’en-tête Authorization :

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

​

URL de base et format de requête

Managed ClickStack

Toutes les requêtes API de Managed ClickStack sont envoyées à la ClickHouse Cloud API :

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

Vous trouverez votre Organization ID dans la console ClickHouse Cloud, sous Organization → Organization details. Votre Service ID est visible dans l’URL du service ou sur sa page de détails.

​

Exemple : Lister les tableaux de bord

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

​

Exemple : Créer une alerte

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

Toutes les requêtes API de Open Source ClickStack sont envoyées au serveur API HyperDX sur le port 8000 :

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

Par exemple, avec un déploiement local par défaut :

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

​

Exemple : Lister les tableaux de bord

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

​

Exemple : Créer une alerte

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

​

Exemple : Interroger les données de série d’un graphique

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