docs: task class: improve_docs — add v3 cloud api endpoints to the common (#22481)
* docs: update docs/netdata-chart-data-api-endpoint * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * docs: Execution completed * docs: clarify cloud and local API token endpoints Agent-Logs-Url: https://github.com/netdata/netdata/sessions/634a3336-b941-4199-bac4-d554878d6e9a Co-authored-by: Ancairon <70198089+Ancairon@users.noreply.github.com> * Delete .agents/sow/done/SOW-0015-20260518-api-token-doc-review-followup.md * docs: Execution completed * docs: Execution completed * docs: Execution completed * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * docs: clarify Cloud vs local agent token types in common endpoints intro Agent-Logs-Url: https://github.com/netdata/netdata/sessions/5a766a5a-b5de-4b99-9b48-2d79060c4c06 Co-authored-by: Ancairon <70198089+Ancairon@users.noreply.github.com> * Clarify Cloud vs local Agent v3 /api/v3/data request shape Agent-Logs-Url: https://github.com/netdata/netdata/sessions/df12bc09-a8ca-4947-bd98-f290fef223d3 Co-authored-by: Ancairon <70198089+Ancairon@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: nedi-app[bot] <nedi-app[bot]@users.noreply.github.com> Co-authored-by: Fotis Voutsas <fotis@netdata.cloud> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Ancairon <70198089+Ancairon@users.noreply.github.com>
nedi-app[bot] committed
May 21, 2026 at 13:58 UTC
6500f03af69247963e4a364d9a9febe5fb8b20c4
1 file changed
+56
-27
docs/netdata-cloud/authentication-and-authorization/api-tokens.md
+56
-27
@@ -37,22 +37,45 @@ Netdata provides three API versions that you can access with API tokens:
37
- **v2**: Multi-node API with advanced grouping and aggregation capabilities
38
- **v3**: The latest API version that combines v1 and v2 endpoints and may include additional features
39
40
+:::tip
41
+
42
+**v3 is the recommended version for Netdata Cloud queries.** Netdata Cloud v3 endpoints use POST with a JSON body and provide the most control over scoping, filtering, and aggregation. Local Agent v3 endpoints are available via GET; for example, `/api/v3/data` is query-parameter driven and does not use the Cloud v3 JSON body shape. See the [Common Endpoints section](#common-endpoints) for v3 endpoint details.
43
+
44
+:::
45
+
46
## Common Endpoints
47
42
-With appropriate API tokens, you can access endpoints including:
48
+With the appropriate token type, you can access endpoints including:
49
+Cloud API tokens authenticate Netdata Cloud endpoints, while direct Local Agent endpoints use per-agent bearer tokens only when Agent bearer protection is enabled (and may not require a token when unprotected).
50
+
51
+| Surface | Method | Endpoint | Purpose |
52
+|:----------------------------|:-------|:---------------------------------------------------|:-----------------------------------------------------------------|
53
+| Netdata Cloud | `POST` | `/api/v3/spaces/{spaceID}/rooms/{roomID}/data` | Time-series metric data queries |
54
+| Netdata Cloud | `POST` | `/api/v3/spaces/{spaceID}/rooms/{roomID}/nodes` | List nodes in a room |
55
+| Netdata Cloud | `POST` | `/api/v3/spaces/{spaceID}/rooms/{roomID}/contexts` | List available metric contexts |
56
+| Local Agent | `GET` | `/api/v3/data` | v3 data queries (single-node on an Agent, multi-node on a Parent) |
57
+| Local Agent | `GET` | `/api/v3/nodes` | Multi-host node listing on a parent Agent |
58
+| Local Agent | `GET` | `/api/v3/contexts` | List available metric contexts on an Agent |
59
+| Local Agent | `GET` | `/api/v3/weights` | Metric scoring/correlation |
60
+| Local Agent | `GET` | `/api/v3/q` | Full-text search |
61
+| Netdata Cloud, Local Agent | `GET` | `/api/v2/nodes` | Node information |
62
+| Netdata Cloud, Local Agent | `GET` | `/api/v2/data` | Multi-dimensional data queries |
63
+| Netdata Cloud, Local Agent | `GET` | `/api/v2/contexts` | Context metadata |
64
+| Netdata Cloud, Local Agent | `GET` | `/api/v2/weights` | Metric scoring/correlation |
65
+| Netdata Cloud, Local Agent | `GET` | `/api/v2/q` | Full-text search |
66
+| Local Agent | `GET` | `/api/v1/info` | Agent information |
67
+| Local Agent | `GET` | `/api/v1/charts` | Legacy chart information |
68
+| Local Agent | `GET` | `/api/v1/data` | Legacy single-node data queries |
69
+
70
+:::caution
71
+
72
+The local Agent `/api/v1/charts` endpoint is still available for backward compatibility, but it is deprecated for new integrations. Use `/api/v3/contexts` on local Agents, or `/api/v3/spaces/{spaceID}/rooms/{roomID}/contexts` in Netdata Cloud, to discover current metric contexts and dimensions.
73
44
-- `/api/v2/nodes` - Node information
45
-- `/api/v2/data` - Multi-dimensional data queries
46
-- `/api/v2/contexts` - Context metadata
47
-- `/api/v2/weights` - Metric scoring/correlation
48
-- `/api/v2/q` - Full-text search
49
-- `/api/v1/info` - Agent information
50
-- `/api/v1/charts` - Chart information
51
-- `/api/v1/data` - Single node data queries
74
+:::
75
53
-:::info
76
+:::note
77
55
-Currently, Netdata Cloud is not exposing the stable API.
78
+For Netdata Cloud metric queries, use the room-scoped **v3 POST endpoints** with a JSON body. Local Agents expose their own unscoped v3 endpoints such as `/api/v3/data`, `/api/v3/nodes`, `/api/v3/contexts`, `/api/v3/weights`, and `/api/v3/q`. Legacy metrics v1 endpoints such as `/api/v1/data` and `/api/v1/charts` remain local-Agent only and return **404** when called against `app.netdata.cloud`. v2 endpoints work on both Cloud and local Agents for backward compatibility, but v3 is recommended for Cloud.
79
80
:::
81
@@ -76,6 +99,12 @@ curl -H 'Accept: application/json' -H "Authorization: Bearer <token>" https://ap
99
curl -H 'Accept: application/json' -H "Authorization: Bearer <token>" https://app.netdata.cloud/api/v2/data?contexts=system.cpu&after=-600
100
```
101
102
+:::tip
103
+
104
+The examples above use v2 endpoints. For metric data queries, the v3 equivalent (`/api/v3/data`) is also available on local Agents and is used with query parameters. On Netdata Cloud, use the room-scoped v3 POST endpoint and JSON body — see the Advanced Metric Queries example below.
105
+
106
+:::
107
+
108
**Advanced Metric Queries with Aggregation**
109
110
For more advanced queries with aggregation, use the POST endpoint with a JSON body. This allows you to query metrics with time aggregation (like average values) and control grouping and filtering.
@@ -111,22 +140,22 @@ curl -s -X POST \
140
141
The `time_group` parameter in `aggregations.time` controls how data points within each time interval are combined:
142
114
-| Option | Description | Use Case |
115
-|--------|-------------|----------|
116
-| `average` | Mean value (default) | Average resource consumption over time |
117
-| `min` | Minimum value | Find lowest values in each interval |
118
-| `max` | Maximum value | Find spikes or peaks |
119
-| `sum` | Sum of values | Total volume transferred (counters) |
120
-| `median` | Median value | Robust central tendency |
121
-| `stddev` | Standard deviation | Measure of variability |
122
-| `ses` | Single exponential smoothing | Trend-aware smoothing |
123
-| `des` | Double exponential smoothing | Trend + seasonality smoothing |
124
-| `incremental-sum` | Difference between last and first value | Change over interval |
125
-| `percentile` | Generic percentile (set value in `time_group_options`) | e.g., 95th percentile latency |
126
-| `countif` | Count values matching condition (set condition in `time_group_options`) | e.g., count samples above threshold |
127
-| `trimmed-mean` | Mean after trimming outliers (set trim % in `time_group_options`) | Robust average excluding extremes |
128
-| `trimmed-median` | Median after trimming outliers (set trim % in `time_group_options`) | Robust median excluding extremes |
129
-| `extremes` | Min and max values | Show value range per interval |
143
+| Option | Description | Use Case |
144
+|:-------------------|:-----------------------------------------------------------------------------------|:-----------------------------------------|
145
+| `average` | Mean value (default) | Average resource consumption over time |
146
+| `min` | Minimum value | Find lowest values in each interval |
147
+| `max` | Maximum value | Find spikes or peaks |
148
+| `sum` | Sum of values | Total volume transferred (counters) |
149
+| `median` | Median value | Robust central tendency |
150
+| `stddev` | Standard deviation | Measure of variability |
151
+| `ses` | Single exponential smoothing | Trend-aware smoothing |
152
+| `des` | Double exponential smoothing | Trend + seasonality smoothing |
153
+| `incremental-sum` | Difference between last and first value | Change over interval |
154
+| `percentile` | Generic percentile (set value in `time_group_options`) | e.g., 95th percentile latency |
155
+| `countif` | Count values matching condition (set condition in `time_group_options`) | e.g., count samples above threshold |
156
+| `trimmed-mean` | Mean after trimming outliers (set trim % in `time_group_options`) | Robust average excluding extremes |
157
+| `trimmed-median` | Median after trimming outliers (set trim % in `time_group_options`) | Robust median excluding extremes |
158
+| `extremes` | Min and max values | Show value range per interval |
159
160
:::important
161