openapi: 3.0.0 info: title: Netdata agent streaming API description: 'Real-time performance and health monitoring. ## API Versions Netdata provides three API versions: - **v1**: The original API, focused on single-node operations - **v2**: Multi-node API with advanced grouping and aggregation capabilities - **v3**: The latest API version that combines v1 and v2 endpoints and may include additional features ### v3 API Endpoints The v3 API provides the current, actively maintained endpoints: - `/api/v3/data` - Multi-dimensional data queries - `/api/v3/weights` - Metric scoring/correlation - `/api/v3/contexts` - Context metadata - `/api/v3/nodes` - Node information - `/api/v3/q` - Full-text search - `/api/v3/alerts` - Alert information - `/api/v3/alert_transitions` - Alert state transitions - `/api/v3/alert_config` - Alert configuration - `/api/v3/functions` - Available functions - `/api/v3/function` - Execute functions - `/api/v3/info` - Agent information - `/api/v3/node_instances` - Node instance information - `/api/v3/stream_path` - Streaming topology - `/api/v3/versions` - Version information - `/api/v3/badge.svg` - Dynamic badges - `/api/v3/allmetrics` - Export metrics - `/api/v3/context` - Single context info - `/api/v3/variable` - Variable information - `/api/v3/config` - Dynamic configuration - `/api/v3/settings` - Agent settings - `/api/v3/me` - Current user information - `/api/v3/claim` - Agent claiming - Additional management and streaming endpoints **Note:** V1 and V2 APIs are deprecated and maintained for backwards compatibility only. New integrations should use V3 exclusively. ' version: v1-rolling contact: name: Netdata Agent API email: info@netdata.cloud url: https://netdata.cloud license: name: GPL v3+ url: https://github.com/netdata/netdata/blob/master/LICENSE servers: - url: https://registry.my-netdata.io - url: http://registry.my-netdata.io - url: http://localhost:19999 tags: - name: streaming paths: /api/v3/stream_info: get: operationId: stream_info tags: - streaming summary: Get streaming information and statistics description: "**V3 SPECIFIC ENDPOINT**\n\nReturns detailed information about Netdata's streaming connections, including sender/receiver\nstatistics, buffer usage, compression ratios, and connection health metrics.\n\n**Streaming Overview:**\nNetdata supports hierarchical streaming where:\n- **Child nodes** send metrics to **parent nodes** for centralization\n- **Parent nodes** aggregate and store metrics from multiple children\n- Streaming uses efficient binary protocol with compression\n- Connections can be TLS-encrypted and authenticated\n\n**Information Provided:**\n- **Connection status**: Active, established, disconnected\n- **Streaming statistics**: Bytes sent/received, compression ratios\n- **Buffer usage**: Current buffer fill levels, drops\n- **Performance metrics**: Streaming latency, throughput\n- **Replication status**: Data replication lag and progress\n- **Protocol version**: Streaming protocol version in use\n\n**Use Cases:**\n- **Monitor streaming health**: Ensure children are connected and streaming\n- **Troubleshoot connectivity**: Identify disconnections and buffer issues\n- **Performance analysis**: Check compression ratios and throughput\n- **Capacity planning**: Monitor buffer usage and network bandwidth\n- **Replication monitoring**: Track data replication status\n\n**Common Usage Patterns:**\n\n1. **Get streaming info for localhost:**\n ```\n /api/v3/stream_info\n ```\n\n2. **Get streaming info for specific node:**\n ```\n /api/v3/stream_info?machine_guid=12345678-1234-1234-1234-123456789012\n ```\n\n**Response Structure:**\nReturns streaming information including:\n- Parent/child relationship status\n- Connection uptime and reconnection count\n- Bytes sent/received with compression ratios\n- Buffer usage (current size, maximum size, drops)\n- Replication lag and status\n- Stream protocol version\n\n**Streaming Modes:**\n- **Sender mode**: Node is streaming data TO a parent\n- **Receiver mode**: Node is receiving data FROM children\n- **Both**: Node can be both sender and receiver\n\n**Health Indicators:**\n- `connected: true/false` - Connection status\n- `buffer_used_percentage` - Buffer fill level\n- `compression_ratio` - Data compression efficiency\n- `replication_lag_seconds` - Data replication delay\n\n**Security & Access Control:**\n- \U0001F513 **Always Public API** - This endpoint is always accessible without authentication\n- **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions\n- **No Authentication:** Cannot be restricted by any configuration\n- **Access:** Available to anyone who can reach the agent's HTTP endpoint\n" parameters: - name: machine_guid in: query required: false description: 'Machine GUID (unique node identifier) to query streaming information for. If not specified, returns streaming information for the local agent. **GUID Format:** - UUID format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` - Case-insensitive - Can be obtained from `/api/v3/nodes` endpoint **Use Cases:** - Query specific child node''s streaming status - Check parent node''s connection to specific child - Diagnostic queries for particular node **Examples:** - `12345678-1234-1234-1234-123456789012` - Specific node - Empty/omitted - Local agent (default) **Invalid GUIDs:** - Malformed UUID: May return error or empty result - Non-existent GUID: Returns empty or not-found response ' schema: type: string format: uuid example: 12345678-1234-1234-1234-123456789012 responses: '200': description: 'Successfully retrieved streaming information. Returns streaming connection details, statistics, and health metrics. ' content: application/json: schema: type: object properties: machine_guid: type: string format: uuid description: Node machine GUID hostname: type: string description: Node hostname streaming_mode: type: string enum: - sender - receiver - both - none description: Streaming mode of this node sender: type: object description: Sender (child→parent) streaming information properties: connected: type: boolean description: Whether sender is currently connected to parent parent_hostname: type: string description: Hostname of parent node uptime_seconds: type: integer description: Connection uptime in seconds reconnects: type: integer description: Number of reconnection attempts bytes_sent: type: integer description: Total bytes sent bytes_compressed: type: integer description: Bytes after compression compression_ratio: type: number description: Compression ratio (original/compressed) buffer_used_bytes: type: integer description: Current send buffer usage buffer_max_bytes: type: integer description: Maximum send buffer size buffer_used_percentage: type: number description: Buffer fill percentage drops: type: integer description: Number of dropped metrics due to buffer overflow receiver: type: object description: Receiver (parent←children) streaming information properties: children: type: array description: Connected child nodes items: type: object properties: machine_guid: type: string format: uuid hostname: type: string connected: type: boolean uptime_seconds: type: integer bytes_received: type: integer replication_lag_seconds: type: integer protocol_version: type: integer description: Streaming protocol version examples: sender_info: value: machine_guid: 12345678-1234-1234-1234-123456789012 hostname: child-node-1 streaming_mode: sender sender: connected: true parent_hostname: parent-node uptime_seconds: 86400 reconnects: 2 bytes_sent: 524288000 bytes_compressed: 104857600 compression_ratio: 5.0 buffer_used_bytes: 1048576 buffer_max_bytes: 10485760 buffer_used_percentage: 10.0 drops: 0 protocol_version: 3 summary: Child node streaming to parent receiver_info: value: machine_guid: 87654321-4321-4321-4321-210987654321 hostname: parent-node streaming_mode: receiver receiver: children: - machine_guid: 12345678-1234-1234-1234-123456789012 hostname: child-node-1 connected: true uptime_seconds: 86400 bytes_received: 524288000 replication_lag_seconds: 2 - machine_guid: 23456789-2345-2345-2345-234567890123 hostname: child-node-2 connected: true uptime_seconds: 43200 bytes_received: 262144000 replication_lag_seconds: 1 protocol_version: 3 summary: Parent node receiving from children '400': description: Invalid machine_guid format. '404': description: Node with specified machine_guid not found. '500': description: Internal server error during streaming info retrieval. components: securitySchemes: bearerAuth: type: http scheme: bearer description: 'Bearer token authentication for API access when bearer protection is enabled. **How to obtain a token:** 1. Token must be obtained via `/api/v3/bearer_get_token` endpoint 2. This endpoint is ACLK-only (requires Netdata Cloud access) 3. Token includes role-based access control and expiration time **How to use:** ``` Authorization: Bearer ``` **When required:** - When bearer protection is enabled on the agent (via `/api/v3/bearer_protection`) - Applies to all APIs with `HTTP_ACCESS_ANONYMOUS_DATA` permission - Does not apply to APIs with `HTTP_ACL_NOCHECK` (always public) - Does not apply to ACLK-only APIs (use cloud authentication) **Token expiration:** - Tokens are time-limited and must be renewed periodically - Expired tokens return HTTP 401 Unauthorized ' aclkAuth: type: http scheme: bearer description: 'ACLK-only authentication - these APIs are ONLY accessible via Netdata Cloud (ACLK). **Access Requirements:** - User must be authenticated via Netdata Cloud (`SIGNED_ID`) - User and agent must be in the same Netdata Cloud space (`SAME_SPACE`) - Additional role-based permissions may apply per endpoint **NOT accessible via:** - Direct HTTP/HTTPS to agent (even with bearer token) - Local dashboard - External integrations **Available only through:** - Netdata Cloud web interface - Netdata Cloud API (ACLK tunnel) **Development mode:** - Can be made available in dev mode with `ACL_DEV_OPEN_ACCESS` flag ' ipAcl: type: apiKey in: header name: X-Forwarded-For description: "IP-based Access Control List restrictions (informational only).\n\n**Configuration:**\nAPIs are subject to IP-based ACL restrictions configured in `netdata.conf`:\n\n```conf\n[web]\n allow dashboard from = *\n allow badges from = *\n allow management from = localhost\n```\n\n**ACL Categories:**\n- `allow dashboard from` - Controls access to metrics, alerts, nodes, functions, config APIs\n- `allow badges from` - Controls access to badge generation APIs\n- `allow management from` - Controls access to management APIs\n\n**Default behavior:**\n- Most APIs allow access from any IP by default\n- Management APIs restrict to localhost by default\n- Can be customized per deployment\n\n**Note:** This is not a standard authentication mechanism but rather IP filtering.\nAPIs with `HTTP_ACL_NOCHECK` bypass all IP restrictions.\n"