chmonitorHTTP API
HTTP API discovery, the public OpenAPI document, authentication, and the stable endpoints agents and scripts should start with.
chmonitor exposes a versioned HTTP API under /api/v1. Agents and scripts should discover it from the live catalog — do not hard-code individual paths when a catalog or OpenAPI document is available.
Prefer discovery over hard-coded paths
Start from GET /.well-known/api-catalog or GET /api/v1/openapi.json. The OpenAPI document is public (no session or API key) and is the stable contract.
Discovery
| Rel | URL | What it is |
|---|---|---|
| API catalog (RFC 9727) | GET /.well-known/api-catalog | Linkset (application/linkset+json) for the /api/v1 service |
service-desc | GET /api/v1/openapi.json | OpenAPI 3.0 document (application/openapi+json) |
service-doc | This page | Human-readable API reference |
status | GET /api/health | Liveness ({"status":"ok"}) |
The dashboard About page (request it with Accept: text/markdown) and GET /auth.md also point at the catalog.
curl -sS https://dash.example.com/.well-known/api-catalog
curl -sS https://dash.example.com/api/v1/openapi.jsonGET /api/v1/openapi.json is public. It returns 200 with openapi, info, and paths for anonymous callers — it does not require a session or API key. The document is the stable public contract (health, hosts, charts, tables, overview, findings, agent, MCP, API-key issuance), assembled from the live dashboard routes — not a two-path stub of /api/health and itself.
Neighboring discovery URLs (same origin):
GET /.well-known/mcp/server-card.json— MCP server cardGET /.well-known/agent-skills/index.json— agent skills indexGET /auth.md— agent authentication notes
Authentication
How /api/v1/* is gated depends on the deployment. See Authentication for the full matrix.
| Mode | Who can call /api/v1/* |
|---|---|
Self-hosted default (CHM_AUTH_PROVIDER=none, no CHM_API_KEY_SECRET) | Anyone who can reach the server |
API keys (CHM_API_KEY_SECRET set) | Authorization: Bearer chm_… (see API keys) |
Cloud / Clerk with public read (CHM_CLERK_PUBLIC_READ=true) | Anonymous reads; writes and the agent still need a session or key |
| Clerk without public read | Signed-in session or chm_ key |
The OpenAPI document itself is exempt from that gate so a client can read the contract before it has credentials.
Useful endpoints
The OpenAPI document is the machine-readable list. These are the endpoints most clients start with:
| Method | Path | Notes |
|---|---|---|
GET | /api/health | Liveness only. Anonymous response is {status, timestamp} — no deployment metadata (#1768). |
GET | /api/v1/openapi.json | This spec. Public. Chart and table {name} enums come from the live registries. |
GET | /api/v1/hosts | Configured ClickHouse hosts (sanitized; no passwords). |
GET | /api/v1/host-status | Version / uptime / hostname. Requires hostId. Pass fleet=1 for the metric bundle. |
GET | /api/v1/overview | Overview KPI batch. Requires hostId. |
GET | /api/v1/charts/{name} | Chart series. hostId defaults to 0. |
GET | /api/v1/tables | Autocomplete list of non-system tables. |
GET | /api/v1/tables/{name} | Named QueryConfig page. hostId defaults to 0. |
GET | /api/v1/findings | Recent findings. Host query param is host (not hostId). |
POST | /api/v1/agent | Streaming AI agent. Authenticated on cloud. |
POST | /api/mcp | Model Context Protocol server — see MCP server. |
POST | /api/v1/auth/api-key | Mint a chm_ key. Bearer must be CHM_API_KEY_SECRET. |
GET | /api/v1/auth/cli | Public CLI auth discovery. Returns method none | api_key | device (plus api, authProvider, deviceLogin, hint). No secrets. Used by chm auth login. |
Most data routes take hostId (query param, default 0) to select a host from the configured host list.
The OpenAPI document is the machine-readable list; this table is the short start set.