Referência da API

Referência da API do ClickStack para gerenciar dashboards, alertas e fontes programaticamente

O ClickStack disponibiliza uma API REST para gerenciar dashboards, alertas e fontes de dados de forma programática. A API está disponível tanto em implantações do Managed ClickStack (ClickHouse Cloud) quanto do ClickStack open source, embora os endpoints e a autenticação sejam diferentes em cada caso.

​

Documentação de referência da API

Managed ClickStack

Para o Managed ClickStack, a API é acessada por meio da ClickHouse Cloud API. Os endpoints do ClickStack estão disponíveis na especificação da Cloud API.

Os seguintes endpoints estão disponíveis:

Recurso	Operações
Dashboards	Criar, listar, buscar, atualizar e excluir dashboards
Alerts	Criar, listar, buscar, atualizar e excluir alertas
Sources	Listar fontes de dados

Open Source ClickStack

Para o Open Source ClickStack, a especificação completa da API é mantida no repositório do HyperDX e pode ser consultada de forma interativa ou baixada como uma especificação OpenAPI:

• Referência interativa da API
• Baixar especificação OpenAPI (JSON)

Os seguintes endpoints estão disponíveis:

Recurso	Operações
Dashboards	Criar, listar, buscar, atualizar e excluir dashboards
Alerts	Criar, listar, buscar, atualizar e excluir alertas
Charts	Consultar dados de séries temporais (somente POST)
Sources	Listar fontes de dados
Webhooks	Listar webhooks

​

Autenticação

Managed ClickStack

O Managed ClickStack usa a API key do ClickHouse Cloud para autenticação por meio de HTTP Basic Authentication. Para criar e gerenciar API keys, consulte Gerenciar API keys.

Inclua o ID da chave e o segredo usando 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

O Open Source ClickStack usa um Bearer token para autenticação por meio de uma Personal API Access Key.

Para obter uma API key:

1. Abra o HyperDX na URL do seu ClickStack (por exemplo, http://localhost:8080)
2. Crie uma conta ou faça login, se necessário
3. Vá para Team Settings → API Keys
4. Copie sua Personal API Access Key

Isso é diferente da API key de ingestão encontrada em Team Settings, que é usada para autenticar dados de telemetria enviados ao collector do OpenTelemetry.

O servidor da API é executado na porta 8000 por padrão (separada da UI na porta 8080). Ao usar a Docker image all-in-one, certifique-se de mapear essa porta explicitamente:

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

Inclua a chave no cabeçalho Authorization:

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

​

URL base e formato da solicitação

Managed ClickStack

Todas as solicitações da API do Managed ClickStack são enviadas para a ClickHouse Cloud API:

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

Você pode encontrar seu Organization ID no console do ClickHouse Cloud, em Organization → Organization details. Seu Service ID fica visível na URL do serviço ou na página de detalhes do serviço.

​

Exemplo: Listar dashboards

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

​

Exemplo: Criar um 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 as solicitações da API do Open Source ClickStack são enviadas para o servidor de API do HyperDX na porta 8000:

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

Por exemplo, em uma implantação local padrão:

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

​

Exemplo: Listar dashboards

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

​

Exemplo: Criar um 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

​

Exemplo: Consultar dados de séries de gráficos

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