| 1 | # Query Netdata alerts via Netdata Cloud |
| 2 | |
| 3 | This guide is part of the [`query-netdata-cloud`](./SKILL.md) skill. |
| 4 | Read the [SKILL.md prerequisites](./SKILL.md#prerequisites) first. |
| 5 | |
| 6 | Alerts are exposed as **REST endpoints** -- not as Functions. Both |
| 7 | Netdata Cloud and the Netdata Agent expose dedicated alert paths. |
| 8 | Use the Cloud-proxied paths by default (no per-agent bearer needed). |
| 9 | Use the agent-direct paths when you need single-host detail or when |
| 10 | Cloud is unavailable (see the sibling |
| 11 | [`query-netdata-agents`](../query-netdata-agents/SKILL.md) skill for |
| 12 | direct-agent auth). |
| 13 | |
| 14 | --- |
| 15 | |
| 16 | ## Mandatory Requirements (READ FIRST) |
| 17 | |
| 18 | 1. **Provide actionable instructions.** Every recommendation ends in |
| 19 | a runnable curl command. |
| 20 | 2. **Never request credentials.** Use `YOUR_API_TOKEN`, |
| 21 | `YOUR_SPACE_ID`, `YOUR_ROOM_ID` placeholders. |
| 22 | 3. **Always include a heredoc body.** Avoids quote-escaping pain. |
| 23 | 4. **Cloud and agent endpoints have different shapes.** Cloud |
| 24 | endpoints aggregate across nodes in a room/space. Agent |
| 25 | endpoints serve a single host. Pick the one that matches the |
| 26 | question. |
| 27 | |
| 28 | --- |
| 29 | |
| 30 | ## Cloud-side endpoints |
| 31 | |
| 32 | Base URL: `https://app.netdata.cloud`. All require |
| 33 | `Authorization: Bearer YOUR_API_TOKEN` and the |
| 34 | `PermissionAlertReadAll` role on the target space (notification |
| 35 | silencing endpoints require write permission). |
| 36 | |
| 37 | ### Current alerts in a room |
| 38 | |
| 39 | `POST /api/v2/spaces/{spaceID}/rooms/{roomID}/alerts` |
| 40 | |
| 41 | ```bash |
| 42 | TOKEN="YOUR_API_TOKEN" |
| 43 | SPACE="YOUR_SPACE_ID" |
| 44 | ROOM="YOUR_ROOM_ID" |
| 45 | |
| 46 | read -r -d '' PAYLOAD <<'EOF' |
| 47 | { |
| 48 | "options": ["instances", "values", "summary", "config"] |
| 49 | } |
| 50 | EOF |
| 51 | |
| 52 | curl -sS -X POST \ |
| 53 | -H 'Content-Type: application/json' \ |
| 54 | -H "Authorization: Bearer $TOKEN" \ |
| 55 | "https://app.netdata.cloud/api/v2/spaces/$SPACE/rooms/$ROOM/alerts" \ |
| 56 | -d "$PAYLOAD" |
| 57 | ``` |
| 58 | |
| 59 | Body accepts optional filters: `status[]` (`CRITICAL`, `WARNING`, |
| 60 | `CLEAR`, etc.), `name` pattern, `alarm_id_filter`, pagination |
| 61 | (`offset`, `limit`), and a time window. Without |
| 62 | `options.instances` the per-instance array is empty -- only the |
| 63 | aggregated `alerts[]` summary is returned. |
| 64 | |
| 65 | Response top-level: `api`, `alerts[]` (one entry per template), |
| 66 | `alert_instances[]` (one entry per running instance, when |
| 67 | requested), `nodes[]`, `timings`. Per-instance compact fields |
| 68 | (verified live): |
| 69 | |
| 70 | | Field | Meaning | |
| 71 | |---|---| |
| 72 | | `nm` | Alert name (e.g. `10min_cpu_iowait`) | |
| 73 | | `ctx` | Context (e.g. `system.cpu`) | |
| 74 | | `ch` / `ch_n` | Chart id / name | |
| 75 | | `st` | Current status (`CRITICAL`, `WARNING`, `CLEAR`, ...) | |
| 76 | | `v` | Current value | |
| 77 | | `t` | Last evaluation timestamp (Unix seconds) | |
| 78 | | `tr_i` | Last transition id (UUID) | |
| 79 | | `tr_v` | Value at last transition | |
| 80 | | `tr_t` | Timestamp of last transition | |
| 81 | | `units` | Unit string | |
| 82 | | `cfg` | **Config hash UUID** -- pass to `/alert_config` as `config` | |
| 83 | | `exec` | Notification executable | |
| 84 | | `tp` / `cl` / `cp` | Type / classification / component | |
| 85 | | `to` | Notification role(s) | |
| 86 | |
| 87 | ### Space-wide alarm stats |
| 88 | |
| 89 | `GET /api/v2/spaces/{spaceID}/alarms` |
| 90 | |
| 91 | ```bash |
| 92 | TOKEN="YOUR_API_TOKEN" |
| 93 | SPACE="YOUR_SPACE_ID" |
| 94 | |
| 95 | curl -sS \ |
| 96 | -H "Authorization: Bearer $TOKEN" \ |
| 97 | "https://app.netdata.cloud/api/v2/spaces/$SPACE/alarms" |
| 98 | ``` |
| 99 | |
| 100 | Returns total counts (`critical`, `warning`, `clear`, `silenced`) |
| 101 | across all rooms in the space. Use to drive a dashboard summary. |
| 102 | |
| 103 | ### Available alert templates / metas |
| 104 | |
| 105 | `GET /api/v2/spaces/{spaceID}/alarms/metas` |
| 106 | |
| 107 | ```bash |
| 108 | TOKEN="YOUR_API_TOKEN" |
| 109 | SPACE="YOUR_SPACE_ID" |
| 110 | |
| 111 | curl -sS \ |
| 112 | -H "Authorization: Bearer $TOKEN" \ |
| 113 | "https://app.netdata.cloud/api/v2/spaces/$SPACE/alarms/metas" |
| 114 | ``` |
| 115 | |
| 116 | Lists every alert template/prototype configured across the space: |
| 117 | names, contexts, severities, available config hashes. Use this to |
| 118 | discover what alerts exist before drilling into a specific one. |
| 119 | |
| 120 | ### Per-room alert summary stats |
| 121 | |
| 122 | `GET /api/v2/spaces/{spaceID}/rooms/{roomID}/alerts_stats` |
| 123 | |
| 124 | ```bash |
| 125 | TOKEN="YOUR_API_TOKEN" |
| 126 | SPACE="YOUR_SPACE_ID" |
| 127 | ROOM="YOUR_ROOM_ID" |
| 128 | |
| 129 | curl -sS \ |
| 130 | -H "Authorization: Bearer $TOKEN" \ |
| 131 | "https://app.netdata.cloud/api/v2/spaces/$SPACE/rooms/$ROOM/alerts_stats" |
| 132 | ``` |
| 133 | |
| 134 | Same shape as `/alarms` but scoped to one room. Optional |
| 135 | node-filter query params. |
| 136 | |
| 137 | ### Misconfigured alerts |
| 138 | |
| 139 | `POST /api/v2/spaces/{spaceID}/rooms/{roomID}/alerts:misconfigured` |
| 140 | |
| 141 | ```bash |
| 142 | TOKEN="YOUR_API_TOKEN" |
| 143 | SPACE="YOUR_SPACE_ID" |
| 144 | ROOM="YOUR_ROOM_ID" |
| 145 | |
| 146 | read -r -d '' PAYLOAD <<'EOF' |
| 147 | { |
| 148 | "categories": ["firing_often", "stuck_raised", "silenced_long", "dispatch_none"], |
| 149 | "thresholds": { |
| 150 | "firing_often_min_count": 10, |
| 151 | "stuck_raised_min_hours": 24 |
| 152 | } |
| 153 | } |
| 154 | EOF |
| 155 | |
| 156 | curl -sS -X POST \ |
| 157 | -H 'Content-Type: application/json' \ |
| 158 | -H "Authorization: Bearer $TOKEN" \ |
| 159 | "https://app.netdata.cloud/api/v2/spaces/$SPACE/rooms/$ROOM/alerts:misconfigured" \ |
| 160 | -d "$PAYLOAD" |
| 161 | ``` |
| 162 | |
| 163 | Categories: `firing_often`, `stuck_raised`, `silenced_long`, |
| 164 | `dispatch_none`. Returns alerts grouped by category with metrics so |
| 165 | you can clean up noisy or broken alert configurations. |
| 166 | |
| 167 | ### Alert state transitions (history) |
| 168 | |
| 169 | `POST /api/v2/spaces/{spaceID}/rooms/{roomID}/alert_transitions` |
| 170 | |
| 171 | ```bash |
| 172 | TOKEN="YOUR_API_TOKEN" |
| 173 | SPACE="YOUR_SPACE_ID" |
| 174 | ROOM="YOUR_ROOM_ID" |
| 175 | # absolute Unix seconds; the endpoint rejects negative or 0 values. |
| 176 | AFTER=$(( $(date +%s) - 86400 )) |
| 177 | |
| 178 | read -r -d '' PAYLOAD <<EOF |
| 179 | { |
| 180 | "after": ${AFTER}, |
| 181 | "before": $(date +%s), |
| 182 | "status": ["CRITICAL", "WARNING"] |
| 183 | } |
| 184 | EOF |
| 185 | |
| 186 | curl -sS -X POST \ |
| 187 | -H 'Content-Type: application/json' \ |
| 188 | -H "Authorization: Bearer $TOKEN" \ |
| 189 | "https://app.netdata.cloud/api/v2/spaces/$SPACE/rooms/$ROOM/alert_transitions" \ |
| 190 | -d "$PAYLOAD" |
| 191 | ``` |
| 192 | |
| 193 | `after` must be **absolute Unix seconds > 0** (verified live; the |
| 194 | endpoint returns |
| 195 | `{"errorMsgKey":"ErrBadRequest","errorMessage":"after parameter must be greater than 0",...}` |
| 196 | otherwise). `before` is also Unix seconds (`0` is rejected; pass |
| 197 | `now` or omit). With an empty body `{}` the endpoint applies its |
| 198 | own default lookback. |
| 199 | |
| 200 | Optional filters: `status[]` (`CRITICAL`, `WARNING`, `CLEAR`, ...), |
| 201 | `alert_names[]`, `node_ids[]`, `context[]`, plus pagination |
| 202 | (`limit`, `last`). |
| 203 | |
| 204 | Response top-level: `api`, `transitions[]`. Each transition record: |
| 205 | `transition_id`, `node_id`, `name`/`alert`, `instance`, `context`, |
| 206 | `when` (unix-seconds), `new` / `old` (`{status, value}`), `summary`, |
| 207 | `info`, `src`, `config_hash_id`, `component`, `classification`, |
| 208 | `to`, `units`, `exec`. |
| 209 | |
| 210 | ### Single alert configuration |
| 211 | |
| 212 | `POST /api/v2/spaces/{spaceID}/rooms/{roomID}/alert_config` |
| 213 | |
| 214 | ```bash |
| 215 | TOKEN="YOUR_API_TOKEN" |
| 216 | SPACE="YOUR_SPACE_ID" |
| 217 | ROOM="YOUR_ROOM_ID" |
| 218 | |
| 219 | read -r -d '' PAYLOAD <<'EOF' |
| 220 | { |
| 221 | "config": "ALERT_CONFIG_HASH_UUID", |
| 222 | "node_id": "YOUR_NODE_UUID" |
| 223 | } |
| 224 | EOF |
| 225 | |
| 226 | curl -sS -X POST \ |
| 227 | -H 'Content-Type: application/json' \ |
| 228 | -H "Authorization: Bearer $TOKEN" \ |
| 229 | "https://app.netdata.cloud/api/v2/spaces/$SPACE/rooms/$ROOM/alert_config" \ |
| 230 | -d "$PAYLOAD" |
| 231 | ``` |
| 232 | |
| 233 | `config` is the hash UUID from the `cfg` field of an alert |
| 234 | instance in the `/alerts` response (request |
| 235 | `options:["instances","config"]` there to get it populated). |
| 236 | Returns the full alert definition: top-level keys `name`, `info`, |
| 237 | `class`, `component`, `selectors`, `status`, `notification`, |
| 238 | `config_hash_id` (echo of input). |
| 239 | |
| 240 | ### Evaluate an alert config against historical data |
| 241 | |
| 242 | `POST /api/v2/spaces/{spaceID}/rooms/{roomID}/alert_config/evaluate` |
| 243 | |
| 244 | ```bash |
| 245 | TOKEN="YOUR_API_TOKEN" |
| 246 | SPACE="YOUR_SPACE_ID" |
| 247 | ROOM="YOUR_ROOM_ID" |
| 248 | |
| 249 | read -r -d '' PAYLOAD <<'EOF' |
| 250 | { |
| 251 | "node_id": "YOUR_NODE_UUID", |
| 252 | "config": "alarm: example_high_cpu\n on: system.cpu\n lookup: average -1m of user\n warn: $this > 70\n crit: $this > 90\n", |
| 253 | "after": -3600, |
| 254 | "before": 0 |
| 255 | } |
| 256 | EOF |
| 257 | |
| 258 | curl -sS -X POST \ |
| 259 | -H 'Content-Type: application/json' \ |
| 260 | -H "Authorization: Bearer $TOKEN" \ |
| 261 | "https://app.netdata.cloud/api/v2/spaces/$SPACE/rooms/$ROOM/alert_config/evaluate" \ |
| 262 | -d "$PAYLOAD" |
| 263 | ``` |
| 264 | |
| 265 | Replays the alert definition against real metric data over the |
| 266 | window. Useful for tuning before deployment. Returns evaluation |
| 267 | results showing what the alert would have done. |
| 268 | |
| 269 | ### AI-assisted alert config generation |
| 270 | |
| 271 | Three companion endpoints that take a context/metric and either |
| 272 | generate, suggest, or explain an alert configuration. All three are |
| 273 | `POST` under `/api/v2/spaces/{spaceID}/alert-config/...`: |
| 274 | |
| 275 | | Endpoint | Purpose | |
| 276 | |---|---| |
| 277 | | `/alert-config/generate` | Produce a full config from a context+metric description | |
| 278 | | `/alert-config/suggest` | Suggest several config variants | |
| 279 | | `/alert-config/explain` | Explain in prose what an existing config does | |
| 280 | |
| 281 | ```bash |
| 282 | TOKEN="YOUR_API_TOKEN" |
| 283 | SPACE="YOUR_SPACE_ID" |
| 284 | |
| 285 | read -r -d '' PAYLOAD <<'EOF' |
| 286 | { |
| 287 | "context": "system.cpu", |
| 288 | "instance": "system", |
| 289 | "metric": "user" |
| 290 | } |
| 291 | EOF |
| 292 | |
| 293 | curl -sS -X POST \ |
| 294 | -H 'Content-Type: application/json' \ |
| 295 | -H "Authorization: Bearer $TOKEN" \ |
| 296 | "https://app.netdata.cloud/api/v2/spaces/$SPACE/alert-config/generate" \ |
| 297 | -d "$PAYLOAD" |
| 298 | ``` |
| 299 | |
| 300 | ### Notification silencing rules |
| 301 | |
| 302 | Silencing rules are Cloud-only (the agent has no silencing REST |
| 303 | API). Five endpoints, all under |
| 304 | `/api/v2/spaces/{spaceID}/notifications/silencing/`: |
| 305 | |
| 306 | | Path | Method | Purpose | |
| 307 | |---|---|---| |
| 308 | | `rules` | GET | List all silencing rules in the space (state: `INACTIVE`, `ACTIVE`, `SCHEDULED`) | |
| 309 | | `rule` | POST | Create a rule | |
| 310 | | `rule/{ruleID}` | PUT | Update a rule | |
| 311 | | `rules/delete` | POST | Bulk-delete rules by ID list | |
| 312 | | `rrule/evaluate` | POST | Evaluate an iCal-style RRULE recurrence expression | |
| 313 | |
| 314 | ```bash |
| 315 | TOKEN="YOUR_API_TOKEN" |
| 316 | SPACE="YOUR_SPACE_ID" |
| 317 | |
| 318 | # List all silencing rules. |
| 319 | curl -sS \ |
| 320 | -H "Authorization: Bearer $TOKEN" \ |
| 321 | "https://app.netdata.cloud/api/v2/spaces/$SPACE/notifications/silencing/rules" |
| 322 | ``` |
| 323 | |
| 324 | Create-rule body: |
| 325 | |
| 326 | ```bash |
| 327 | TOKEN="YOUR_API_TOKEN" |
| 328 | SPACE="YOUR_SPACE_ID" |
| 329 | |
| 330 | read -r -d '' PAYLOAD <<'EOF' |
| 331 | { |
| 332 | "name": "Maintenance window for db cluster", |
| 333 | "room_ids": ["YOUR_ROOM_ID"], |
| 334 | "node_ids": [], |
| 335 | "host_labels": { "role": "database" }, |
| 336 | "alert_names": [], |
| 337 | "alert_contexts": ["disk.space"], |
| 338 | "severities": ["WARNING", "CRITICAL"], |
| 339 | "starts_at": 1700000000, |
| 340 | "lasts_until": 1700003600, |
| 341 | "rrule": "" |
| 342 | } |
| 343 | EOF |
| 344 | |
| 345 | curl -sS -X POST \ |
| 346 | -H 'Content-Type: application/json' \ |
| 347 | -H "Authorization: Bearer $TOKEN" \ |
| 348 | "https://app.netdata.cloud/api/v2/spaces/$SPACE/notifications/silencing/rule" \ |
| 349 | -d "$PAYLOAD" |
| 350 | ``` |
| 351 | |
| 352 | `rrule` is an iCalendar RFC 5545 recurrence string (e.g. |
| 353 | `FREQ=WEEKLY;BYDAY=SA,SU`). Use `rrule/evaluate` first to confirm |
| 354 | the schedule before creating. |
| 355 | |
| 356 | --- |
| 357 | |
| 358 | ## Direct-agent fallback (single-host alerts) |
| 359 | |
| 360 | When you need detail for a specific host or Cloud is unavailable, |
| 361 | talk to the agent directly. All paths below are reachable at |
| 362 | `http://<agent>:19999/host/<node-uuid>` and require a per-agent |
| 363 | bearer if the agent is bearer-protected (see |
| 364 | [query-netdata-agents](../query-netdata-agents/SKILL.md) for the |
| 365 | mint flow). |
| 366 | |
| 367 | ### Multi-status alerts (preferred -- agent v3) |
| 368 | |
| 369 | `POST /api/v3/alerts` |
| 370 | |
| 371 | ```bash |
| 372 | HOST="agent.example:19999" |
| 373 | NODE="YOUR_NODE_UUID" |
| 374 | BEARER="MINTED_AGENT_BEARER" |
| 375 | |
| 376 | read -r -d '' PAYLOAD <<'EOF' |
| 377 | { |
| 378 | "options": ["summary", "values", "instances"] |
| 379 | } |
| 380 | EOF |
| 381 | |
| 382 | curl -sS -X POST \ |
| 383 | -H "X-Netdata-Auth: Bearer $BEARER" \ |
| 384 | -H 'Content-Type: application/json' \ |
| 385 | "http://$HOST/host/$NODE/api/v3/alerts" \ |
| 386 | -d "$PAYLOAD" |
| 387 | ``` |
| 388 | |
| 389 | Same body fields as the Cloud-proxied `/alerts` endpoint |
| 390 | (`status[]`, `name`, time range, options). Response is a |
| 391 | single-node alert table. The handler at |
| 392 | `<repo>/src/web/api/v2/api_v2_alerts.c` is shared with `/api/v2/alerts` |
| 393 | (use v2 only on older agents that lack v3). |
| 394 | |
| 395 | ### Alert transitions on a single agent (agent v3) |
| 396 | |
| 397 | `POST /api/v3/alert_transitions` |
| 398 | |
| 399 | Same body shape as the Cloud transitions endpoint; result is |
| 400 | single-host. Shared handler with `/api/v2/alert_transitions`; use |
| 401 | v3 by default. |
| 402 | |
| 403 | ### Single alert config on a single agent (agent v3) |
| 404 | |
| 405 | `GET /api/v3/alert_config?config=CONFIG_HASH_UUID` |
| 406 | |
| 407 | ```bash |
| 408 | HOST="agent.example:19999" |
| 409 | NODE="YOUR_NODE_UUID" |
| 410 | BEARER="MINTED_AGENT_BEARER" |
| 411 | CFG="ALERT_CONFIG_HASH_UUID" # the cfg field of an alert instance |
| 412 | |
| 413 | curl -sS \ |
| 414 | -H "X-Netdata-Auth: Bearer $BEARER" \ |
| 415 | "http://$HOST/host/$NODE/api/v3/alert_config?config=$CFG" |
| 416 | ``` |
| 417 | |
| 418 | `config` is the hash UUID (the `cfg` field of an alert instance). |
| 419 | The Cloud endpoint above points to the same data; use this only |
| 420 | for direct-agent workflows. Response top-level keys verified live: |
| 421 | `name`, `info`, `class`, `component`, `selectors`, `status`, |
| 422 | `notification`, `config_hash_id`. Shared handler with v2; v3 is |
| 423 | the default. |
| 424 | |
| 425 | ### Legacy v1 alarm endpoints (use only on pre-v2 agents) |
| 426 | |
| 427 | These remain only for agents older than v1.40 that have no v2/v3 |
| 428 | alert endpoints. On any modern agent, use the v3 endpoints above. |
| 429 | |
| 430 | | Path | Method | Purpose | |
| 431 | |---|---|---| |
| 432 | | `/api/v1/alarms` | GET | Active alarms; query `?all=true` for inactive too | |
| 433 | | `/api/v1/alarms_values` | GET | Numeric state per alarm | |
| 434 | | `/api/v1/alarm_log` | GET | History; `?after=<unix-seconds>&chart=<name>` | |
| 435 | | `/api/v1/alarm_count` | GET | Count by status; `?status=CRITICAL&context=<name>` | |
| 436 | | `/api/v1/alarm_variables` | GET | Per-chart alert variables; `?chart=<name>` (required) | |
| 437 | | `/api/v1/variable` | GET | Single variable lookup; `?chart=<name>&variable=<name>` | |
| 438 | |
| 439 | ```bash |
| 440 | HOST="agent.example:19999" |
| 441 | NODE="YOUR_NODE_UUID" |
| 442 | BEARER="MINTED_AGENT_BEARER" |
| 443 | |
| 444 | # Active alarms only |
| 445 | curl -sS \ |
| 446 | -H "X-Netdata-Auth: Bearer $BEARER" \ |
| 447 | "http://$HOST/host/$NODE/api/v1/alarms" |
| 448 | |
| 449 | # Alarm transition history since a given timestamp |
| 450 | curl -sS \ |
| 451 | -H "X-Netdata-Auth: Bearer $BEARER" \ |
| 452 | "http://$HOST/host/$NODE/api/v1/alarm_log?after=1700000000" |
| 453 | ``` |
| 454 | |
| 455 | Migration: `/api/v1/alarms` -> `/api/v2/alerts`, |
| 456 | `/api/v1/alarm_log` -> `/api/v2/alert_transitions`. |
| 457 | |
| 458 | --- |
| 459 | |
| 460 | ## Question-to-endpoint cheatsheet |
| 461 | |
| 462 | | Question | Cloud | Agent direct | |
| 463 | |---|---|---| |
| 464 | | What alerts are firing across the room? | `POST /api/v2/spaces/{sp}/rooms/{rm}/alerts` | `POST /host/{node}/api/v3/alerts` | |
| 465 | | What alerts are firing across the entire space? | `GET /api/v2/spaces/{sp}/alarms` | (run per-room) | |
| 466 | | Which alert templates are configured? | `GET /api/v2/spaces/{sp}/alarms/metas` | (per-host config inspection) | |
| 467 | | Show alert state transitions over the last 24h | `POST /api/v2/spaces/{sp}/rooms/{rm}/alert_transitions` body `{after:<unix-s>,before:<unix-s>,...}` | `POST /host/{node}/api/v3/alert_transitions` | |
| 468 | | Get the full configuration of a specific alert | `POST /api/v2/spaces/{sp}/rooms/{rm}/alert_config` body `{config,node_id}` | `GET /host/{node}/api/v3/alert_config?config=...` | |
| 469 | | Evaluate a candidate alert config against history | `POST /api/v2/spaces/{sp}/rooms/{rm}/alert_config/evaluate` | not available (Cloud-only) | |
| 470 | | Generate / suggest / explain an alert config | `POST /api/v2/spaces/{sp}/alert-config/{generate,suggest,explain}` | not available (Cloud-only) | |
| 471 | | Which alerts are misconfigured (firing-often, stuck-raised, silenced-long, dispatch-none)? | `POST /api/v2/spaces/{sp}/rooms/{rm}/alerts:misconfigured` | not available (Cloud-only) | |
| 472 | | What silencing rules are active or scheduled? | `GET /api/v2/spaces/{sp}/notifications/silencing/rules` | not available (Cloud-only) | |
| 473 | | Create / update / delete a silencing rule | `POST/PUT/DELETE /api/v2/spaces/{sp}/notifications/silencing/rule[s]/...` | not available (Cloud-only) | |
| 474 | | Reload alert definitions on the agent | not exposed via REST | not exposed via REST -- use SIGHUP or dyncfg | |
| 475 | |
| 476 | --- |
| 477 | |
| 478 | ## Limits and gotchas |
| 479 | |
| 480 | - **`PermissionAlertReadAll` is required** for all alert reads -- |
| 481 | `scope:all` tokens have it; `scope:grafana-plugin` tokens do |
| 482 | NOT. If you get HTTP 403, mint a wider-scoped token. |
| 483 | - **Silencing rules are Cloud-only.** The agent's internal |
| 484 | `SILENCER` structures are not REST-addressable. There is no |
| 485 | `/api/v[123]/silencers` on the agent. |
| 486 | - **No REST endpoint for "reload alert configs"** on either side. |
| 487 | The agent reloads on `SIGHUP` or via the dyncfg callback at |
| 488 | `src/health/health_dyncfg.c`. For programmatic config changes, |
| 489 | push files to `etc/netdata/health.d/` and signal the agent. |
| 490 | - **`config_hash_id` is required for `/alert_config`** on both |
| 491 | sides. Get it from the alert metadata (`/alerts` response, |
| 492 | `config_hash_id` field, or `/alarms/metas` for templates). |
| 493 | - **Agent-direct paths return single-host data.** For aggregated |
| 494 | cross-room/cross-space queries, you must use Cloud or aggregate |
| 495 | agent responses client-side. |
| 496 | - **`alert_transitions` time bounds are seconds, NOT |
| 497 | milliseconds.** Negative values are relative offsets from "now". |
| 498 | This differs from `systemd-journal` time bounds (microseconds). |