API reference

Base URL: https://qooqes.online/api/v1. All requests require a bearer token; all responses are JSON.

Authentication

Authorization: Bearer <token>

Tokens are per-host, issued when a host is registered. A missing or invalid token returns 401. There is no separate API key for read-only use yet — the host token covers both ingest and read endpoints.

GET /v1/hosts

Lists registered hosts and their last check-in.

curl -H "Authorization: Bearer $AGENT_TOKEN" \
  https://qooqes.online/api/v1/hosts

{
  "hosts": [
    { "id": "web-03", "tags": ["prod", "eu-west"], "last_seen": "2026-07-30T12:00:04Z", "status": "up" },
    { "id": "db-01",  "tags": ["prod", "eu-west"], "last_seen": "2026-07-30T11:59:58Z", "status": "up" }
  ],
  "count": 2
}

GET /v1/metrics

Returns time series points for one host and one metric name. since is RFC 3339; defaults to 1 hour ago if omitted.

curl -H "Authorization: Bearer $AGENT_TOKEN" \
  "https://qooqes.online/api/v1/metrics?host_id=web-03&metric=cpu.load1&since=2026-07-30T00:00:00Z"

{
  "host_id": "web-03",
  "metric": "cpu.load1",
  "points": [
    { "t": "2026-07-30T11:59:00Z", "v": 0.38 },
    { "t": "2026-07-30T12:00:00Z", "v": 0.42 }
  ]
}

POST /v1/ingest

Accepts a batch of metrics from an agent. Up to 500 metrics per request. Rejects timestamps more than 5 minutes ahead of server time (clock skew guard).

curl -X POST https://qooqes.online/api/v1/ingest \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "host_id": "web-03",
    "collected_at": "2026-07-30T12:00:04Z",
    "metrics": {
      "cpu.load1": 0.42,
      "mem.used_pct": 61.3,
      "disk.free_bytes": 128849018880
    }
  }'

{
  "accepted": 3,
  "rejected": 0,
  "next_expected_at": "2026-07-30T12:00:34Z"
}

GET /v1/incidents

Lists incidents opened by threshold rules. Filter with state=open, state=acknowledged, or state=closed.

curl -H "Authorization: Bearer $AGENT_TOKEN" \
  "https://qooqes.online/api/v1/incidents?state=open"

{
  "incidents": [
    {
      "id": "inc_4821",
      "host_id": "db-01",
      "opened_at": "2026-07-29T03:14:00Z",
      "state": "open",
      "reason": "disk.free_bytes below threshold"
    }
  ],
  "count": 1
}

POST /v1/incidents/{id}/ack

Acknowledges an open incident. Does not close it — closing happens automatically when the underlying metric recovers past the threshold.

curl -X POST -H "Authorization: Bearer $AGENT_TOKEN" \
  https://qooqes.online/api/v1/incidents/inc_4821/ack

{
  "id": "inc_4821",
  "state": "acknowledged",
  "acknowledged_at": "2026-07-30T12:05:11Z"
}

Response codes

Code	Meaning
200	Request succeeded.
400	Malformed JSON or missing required field.
401	Missing or invalid bearer token.
404	Unknown host_id or incident id.
429	Ingest rate limit exceeded. Response includes Retry-After.
500	Transient server error. Safe to retry with backoff.

Removed in 0.9.3: GET /v1/ping — use GET /v1/hosts with an empty result set as a liveness check instead. See the changelog.