The webrtc API from Netdata — 2 operation(s) for webrtc.
openapi: 3.0.0
info:
title: Netdata agent webrtc 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: webrtc
paths:
/api/v3/rtc_offer:
post:
operationId: rtcOffer3
tags:
- webrtc
summary: Establish WebRTC peer connection by exchanging SDP offer/answer
description: '**WebRTC Connection Establishment**
This endpoint implements the WebRTC signaling process for establishing peer-to-peer data connections with the Netdata agent. It follows the standard WebRTC negotiation flow using SDP (Session Description Protocol) offer/answer exchange.
**How It Works:**
1. Client creates a WebRTC peer connection and generates an SDP offer
2. Client sends the SDP offer to this endpoint via POST request body
3. Server processes the offer, configures ICE servers and connection parameters
4. Server generates and returns an SDP answer with ICE candidates
5. Client sets the answer to complete the WebRTC connection handshake
6. Data channels can then be established for real-time communication
**Use Cases:**
- **Real-time dashboards:** Stream live metrics with minimal latency using WebRTC data channels
- **Browser-based monitoring:** Enable direct peer-to-peer connections from web browsers to agents
- **NAT traversal:** Establish connections through firewalls and NATs using ICE/STUN/TURN
- **Low-latency updates:** Bypass HTTP polling for instant metric updates via WebRTC
- **Bi-directional communication:** Enable interactive control and monitoring in real-time
**Connection Configuration:**
- Maximum message size: 5 MiB (local), negotiated with remote peer
- ICE transport policy: All (both UDP and TCP)
- Automatic ICE candidate gathering
- Support for STUN/TURN servers
- Automatic port range selection
- MTU auto-detection
**Important Notes:**
- WebRTC must be enabled in agent configuration (enabled by default in debug builds)
- The endpoint waits for ICE gathering to complete before returning the answer
- The SDP offer must be valid and include media descriptions
- Response includes both SDP answer and gathered ICE candidates
- Connections are automatically cleaned up on timeout or disconnection
**Example SDP Offer Structure:**
```
v=0
o=- 123456789 2 IN IP4 127.0.0.1
s=-
t=0 0
a=group:BUNDLE 0
a=msid-semantic: WMS
m=application 9 UDP/DTLS/SCTP webrtc-datachannel
c=IN IP4 0.0.0.0
a=ice-ufrag:XXXX
a=ice-pwd:YYYY
a=fingerprint:sha-256 ZZ:ZZ:...
a=setup:actpass
a=mid:0
a=sctp-port:5000
a=max-message-size:65536
```
**Performance Characteristics:**
- Synchronous operation (blocks until ICE gathering completes)
- Typical response time: 100-500ms (depending on ICE gathering)
- Supports multiple concurrent connections
- Automatic connection cleanup on idle timeout
**Security & Access Control:**
- ⚠️ **ACLK-Only API** - This endpoint is ONLY accessible via Netdata Cloud (ACLK connection)
- **NOT accessible via:** Direct HTTP/HTTPS to agent, local dashboard, or external tools
- **Authentication:** Requires Netdata Cloud authentication (`SIGNED_ID` + `SAME_SPACE`)
- **User Requirements:** User must be authenticated and in the same cloud space as the agent
- **Development Mode:** Can be enabled for testing with `ACL_DEV_OPEN_ACCESS` flag
'
security:
- aclkAuth: []
requestBody:
required: true
content:
text/plain:
schema:
type: string
description: 'SDP (Session Description Protocol) offer from the client''s WebRTC peer connection.
Must be a valid SDP offer string containing session information, media descriptions,
ICE credentials, and DTLS fingerprint.
'
example: 'v=0
o=- 123456789 2 IN IP4 127.0.0.1
s=-
t=0 0
a=group:BUNDLE 0
m=application 9 UDP/DTLS/SCTP webrtc-datachannel
c=IN IP4 0.0.0.0
a=ice-ufrag:abcd1234
a=ice-pwd:efgh5678ijkl9012mnop3456
a=fingerprint:sha-256 AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB
a=setup:actpass
a=mid:0
a=sctp-port:5000
a=max-message-size:65536
'
responses:
'200':
description: 'SDP answer successfully generated. The response contains the server''s SDP answer
including all gathered ICE candidates. The client should set this as the remote
description to complete the WebRTC handshake.
'
content:
application/json:
schema:
type: object
properties:
sdp:
type: string
description: 'SDP answer from the server containing session information, media descriptions,
ICE credentials, DTLS fingerprint, and all gathered ICE candidates.
'
type:
type: string
enum:
- answer
description: SDP message type (always "answer" for responses)
example:
sdp: 'v=0
o=- 987654321 2 IN IP4 192.168.1.100
s=-
t=0 0
a=group:BUNDLE 0
m=application 9 UDP/DTLS/SCTP webrtc-datachannel
c=IN IP4 192.168.1.100
a=candidate:1 1 udp 2130706431 192.168.1.100 54321 typ host
a=candidate:2 1 udp 1694498815 203.0.113.1 54321 typ srflx raddr 192.168.1.100 rport 54321
a=ice-ufrag:wxyz9876
a=ice-pwd:stuv5432wxyz1098abcd7654
a=fingerprint:sha-256 12:34:56:78:9A:BC:DE:F0:12:34:56:78:9A:BC:DE:F0:12:34:56:78:9A:BC:DE:F0:12:34:56:78:9A:BC:DE:F0:12
a=setup:active
a=mid:0
a=sctp-port:5000
a=max-message-size:5242880
'
type: answer
'400':
description: 'Bad request due to one of the following reasons:
- WebRTC is not enabled on this agent (check configuration)
- No SDP offer provided in request body
- Invalid SDP format or content
- Missing required SDP fields (ice-ufrag, ice-pwd, fingerprint)
'
'500':
description: Internal server error during WebRTC connection establishment or ICE gathering.
/api/v2/rtc_offer:
post:
deprecated: true
operationId: rtcOffer2
tags:
- webrtc
summary: 'OBSOLETE: Establish WebRTC connection (use /api/v3/rtc_offer instead)'
description: '**⚠️ OBSOLETE API - Will be removed in future versions**
This endpoint is deprecated. Use `/api/v3/rtc_offer` instead, which provides the same functionality.
**Migration:** Replace `/api/v2/rtc_offer` with `/api/v3/rtc_offer` in all API calls.
Establishes WebRTC peer-to-peer connection by exchanging SDP offer/answer for real-time data channels.
**Security & Access Control:**
- ⚠️ **ACLK-Only API** - Accessible only via Netdata Cloud (ACLK connection)
- Same access requirements as v3 version
'
security:
- aclkAuth: []
requestBody:
required: true
content:
text/plain:
schema:
type: string
description: SDP offer from client's WebRTC peer connection
responses:
'200':
description: SDP answer successfully generated
'400':
description: Invalid or missing SDP offer
'500':
description: Internal error during WebRTC connection establishment
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 <token>
```
**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"