docs: Document Cloud API space/room composite endpoints#21942
Open
docs: Document Cloud API space/room composite endpoints#21942
Conversation
Add comprehensive documentation for Cloud API space/room composite endpoints including:
- POST /api/v1/spaces/{spaceID}/rooms/{roomID}/data endpoint
- Aggregation methods (avg/min/max/sum)
- Grouping options (dimension/node/chart/label)
- Time grouping configuration
- API version mapping between Agent API v3 and Cloud API v1/v2
- Practical curl example with aggregations
This addresses user confusion about the correct endpoint structure and API versioning for aggregated multi-node queries.
|
Netdata Docs Bot seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account. You have signed the CLA already but the status is still pending? Let us recheck it. |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
No issues found across 1 file
Confidence score: 5/5
- Automated review surfaced no issues in the provided summaries.
- No files require special attention.
Architecture diagram
sequenceDiagram
participant Client as External Client
participant Gateway as Cloud API Gateway
participant Auth as Auth Service
participant QueryEng as Cloud Query Engine
participant Agents as Netdata Agents (Nodes)
Note over Client,Agents: NEW: Multi-Node Aggregated Data Flow (Cloud API v1)
Client->>Gateway: POST /api/v1/spaces/{sID}/rooms/{rID}/data
Note right of Client: Body: { aggregations, scope, format: "json2" }
Gateway->>Auth: Validate API Token (scope:all)
Auth-->>Gateway: Authorized
Gateway->>QueryEng: Execute composite query
QueryEng->>QueryEng: NEW: Resolve Space/Room to Node List
rect rgb(23, 37, 84)
Note right of QueryEng: Parallel Data Retrieval
loop For each Node in Room/Scope
QueryEng->>Agents: Fetch metrics (via ACLK)
Agents-->>QueryEng: Raw metric data
end
end
QueryEng->>QueryEng: CHANGED: Apply aggregation logic<br/>(avg, min, max, sum)
QueryEng->>QueryEng: CHANGED: Apply grouping<br/>(dimension, node, chart, label)
QueryEng-->>Gateway: Formatted Result (json2)
Gateway-->>Client: 200 OK (Aggregated Dataset)
Note over Client,Gateway: API Version Comparison
alt Listing Resources
Client->>Gateway: GET /api/v2/spaces | /api/v2/nodes
else Direct Agent Query (Non-Cloud)
Client->>Agents: GET /api/v3/data
end
Member
Author
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
Ancairon
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds comprehensive documentation for Netdata Cloud API space/room composite endpoints, addressing the user query from issue #620.
Changes
Context
The user was attempting to use `/api/v3/spaces/.../rooms/.../data` but receiving 404 errors. This documentation clarifies that:
Related
Summary by cubic
Adds documentation for Netdata Cloud space/room composite endpoints. Clarifies how to run multi-node aggregated queries and which API versions to use.
api-tokens.mdforPOST /api/v1/spaces/{spaceID}/rooms/{roomID}/data.v3(agent queries), Cloud APIv1(space/room composites), Cloud APIv2(listing resources).Written for commit f13ede7. Summary will update on new commits.