Skip to content

API Reference

Hexcovery exposes a small, deliberate programmatic surface. Everything an automation or integration needs is reachable with a tenant-scoped API key over HTTPS — there is no raw-SQL endpoint, no page-scraping API, and no way to reach ClickHouse directly. You query with OQL, mark events with annotations, and report scheduled-job runs with heartbeats. Bulk telemetry (traces, logs, metrics) arrives over OTLP on gRPC — see Sending Data.

The programmatic surface

These are the only HTTP endpoints an API key can touch. Authenticate every request with the X-API-Key header.

Endpoint Method Purpose Reference
/api/v1/dsl POST Execute an OQL query and get back columns + rows Query API
/api/v1/annotations GET List annotations (filter by time range, name prefix) Annotations API
/api/v1/annotations POST Create an annotation (e.g. a CI/CD deploy marker) Annotations API
/api/v1/annotations/:id PUT Update an annotation Annotations API
/api/v1/annotations/:id DELETE Delete an annotation Annotations API
/api/v1/heartbeat/* POST Report a cron-job run (start / log / end / ping) Heartbeat API

Plus OTLP ingest on :4317 (gRPC) for traces, logs, and metrics — covered under Sending Data, not here.

That is the complete list. Anything else under /api/v1/* (overview, hosts, logs, traces, schema, dashboards, …) backs the dashboard UI and requires an authenticated user session (a JWT), not an API key.

Authentication in one line

curl -X POST https://server/api/v1/dsl \
  -H "X-API-Key: $HEXCOVERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT avg(cpu_user_pct) FROM host LAST 1h"}'

The X-API-Key header is the only credential automation uses. The Authorization: Bearer slot is reserved for dashboard JWTs and will not accept an API key. See Authentication for the full model, and API keys for creating and rotating keys.

Pages