| 1 | # List rooms 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 | Rooms are Cloud-only organizational units. There is no agent-side |
| 7 | equivalent. |
| 8 | |
| 9 | --- |
| 10 | |
| 11 | ## Endpoint |
| 12 | |
| 13 | `GET /api/v2/spaces/{spaceID}/rooms` -- list all rooms the user can |
| 14 | see in a space. |
| 15 | |
| 16 | ## Use the wrapper |
| 17 | |
| 18 | ```bash |
| 19 | source "$(git rev-parse --show-toplevel)/.agents/skills/query-netdata-agents/scripts/_lib.sh" |
| 20 | agents_load_env |
| 21 | |
| 22 | # All rooms in a space. |
| 23 | agents_query_cloud GET "/api/v2/spaces/$SPACE/rooms" |
| 24 | ``` |
| 25 | |
| 26 | ## Per-room response fields |
| 27 | |
| 28 | Verified live -- response is a JSON array, each entry: |
| 29 | |
| 30 | | Field | Description | |
| 31 | |---|---| |
| 32 | | `id` | **Room UUID.** Use this anywhere the API expects a room id. | |
| 33 | | `slug` | URL-safe identifier (e.g. `agent-events-r0gtre6`) | |
| 34 | | `name` | Human-readable name (e.g. `agent-events`) | |
| 35 | | `description` | Free-form description (may be `null`) | |
| 36 | | `private` | `true` if invitation-only | |
| 37 | | `untouchable` | `true` for the auto-managed "All nodes" room (cannot be deleted) | |
| 38 | | `node_count` | Number of nodes assigned to this room | |
| 39 | | `member_count` | Number of users in this room | |
| 40 | | `isMember` | Whether the calling user is a member | |
| 41 | | `silencing_state` | Notification silencing state for the calling user | |
| 42 | | `permissions` | Array of permission strings the caller has on the room | |
| 43 | | `createdAt` | RFC3339 timestamp | |
| 44 | |
| 45 | ## Common patterns |
| 46 | |
| 47 | ```bash |
| 48 | # Find the room id by name. |
| 49 | agents_query_cloud GET "/api/v2/spaces/$SPACE/rooms" \ |
| 50 | | jq -r --arg NAME "agent-events" '.[] | select(.name==$NAME) | .id' |
| 51 | |
| 52 | # Rooms with at least one reachable node, sorted by node count. |
| 53 | agents_query_cloud GET "/api/v2/spaces/$SPACE/rooms" \ |
| 54 | | jq -r 'sort_by(-.node_count) | .[] | select(.node_count > 0) | "\(.name)\t\(.node_count)"' |
| 55 | |
| 56 | # Rooms the caller can administer. |
| 57 | agents_query_cloud GET "/api/v2/spaces/$SPACE/rooms" \ |
| 58 | | jq -r '.[] | select(.permissions | index("room:Delete")) | .name' |
| 59 | ``` |
| 60 | |
| 61 | ## Limits and gotchas |
| 62 | |
| 63 | - **The "All nodes" room is special.** It auto-includes every |
| 64 | node in the space and cannot be deleted. Filter on |
| 65 | `untouchable=true` if you need it specifically. |
| 66 | - **`node_count` and `member_count` are server-side counts** -- |
| 67 | no need to fetch nodes/members just to get the totals. |
| 68 | - **Permissions vary per user.** The same room returns different |
| 69 | `permissions[]` arrays depending on the caller's role; another |
| 70 | user may see fewer permissions. |
| 71 | |
| 72 | ## See also |
| 73 | |
| 74 | - [query-nodes.md](./query-nodes.md) -- enumerate nodes in a |
| 75 | specific room. |
| 76 | - [query-members.md](./query-members.md) -- list members of a |
| 77 | space (rooms inherit space membership scoped by room |
| 78 | permissions). |
| 79 | - [query-alerts.md](./query-alerts.md) -- silencing rules |
| 80 | reference rooms by id. |