Everything related to managing netdata Agents
openapi: 3.0.0
info:
title: Netdata agent management 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: management
description: Everything related to managing netdata Agents
paths:
/api/v1/manage/health:
get:
deprecated: true
operationId: health1
tags:
- management
summary: 'Accesses the health management API to control health checks and notifications at runtime.
'
description: 'Available from Netdata v1.12 and above, protected via bearer authorization. Especially useful for maintenance periods, the API allows you to disable health checks completely, silence alarm notifications, or Disable/Silence specific alarms that match selectors on alarm/template name, chart, context, host and family. For the simple disable/silence all scenarios, only the cmd parameter is required. The other parameters are used to define alarm selectors. For more information and examples, refer to the netdata documentation.
**Security & Access Control:**
- 🔧 **Management API** - Subject to management ACL restrictions
- **IP Restrictions:** Controlled by `allow management from` in netdata.conf (default: localhost only)
- **Internal Permissions:** Each management action has its own permission requirements
- **No Bearer Protection:** Not subject to bearer token authentication
'
parameters:
- name: cmd
in: query
description: 'DISABLE ALL: No alarm criteria are evaluated, nothing is written in the alarm log. SILENCE ALL: No notifications are sent. RESET: Return to the default state. DISABLE/SILENCE: Set the mode to be used for the alarms matching the criteria of the alarm selectors. LIST: Show active configuration.
'
required: false
schema:
type: string
enum:
- DISABLE ALL
- SILENCE ALL
- DISABLE
- SILENCE
- RESET
- LIST
- name: alarm
in: query
description: The expression provided will match both `alarm` and `template` names.
schema:
type: string
- name: chart
in: query
description: Chart ids/names, as shown on the dashboard. These will match the `on` entry of a configured `alarm`.
schema:
type: string
- name: context
in: query
description: Chart context, as shown on the dashboard. These will match the `on` entry of a configured `template`.
schema:
type: string
- name: hosts
in: query
description: The hostnames that will need to match.
schema:
type: string
responses:
'200':
description: A plain text response based on the result of the command.
'403':
description: Bearer authentication error.
/api/v1/aclk:
get:
deprecated: true
operationId: aclk1
tags:
- management
summary: Get information about current ACLK state
description: 'ACLK endpoint returns detailed information about current state of ACLK (Agent to Cloud communication).
**Security & Access Control:**
- 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply
- **Default Access:** Public (no authentication required)
- **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token
- **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf
- **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools
'
security:
- {}
- bearerAuth: []
responses:
'200':
description: JSON object with ACLK information.
content:
application/json:
schema:
$ref: '#/components/schemas/aclk_state'
/api/v1/dbengine_stats:
get:
deprecated: true
operationId: dbengine_stats1
tags:
- management
summary: '[DEPRECATED] Get DBEngine storage statistics'
description: '**[DEPRECATED - Use Netdata Cloud or internal metrics for storage monitoring]**
**DBEngine Storage Statistics**
Returns detailed statistics about Netdata''s DBEngine storage system for all configured storage tiers. DBEngine is Netdata''s high-performance time-series database that stores metrics on disk.
**Statistics Provided (per tier):**
**Datafiles:**
- Active datafiles count
- Total datafiles (active + archived)
- Datafile size limits
**Extents:**
- Number of extents (storage chunks)
- Extent compression statistics
- Extent allocation and fragmentation
**Pages:**
- Page cache statistics
- Page types (hot, cold, compressed)
- Page I/O statistics
**Compression:**
- Compression ratios achieved
- Compression algorithm efficiency
- Space saved by compression
**Retention:**
- Actual retention achieved
- Retention limits and targets
- Disk space usage
**Performance:**
- Read/write rates
- Cache hit ratios
- I/O wait times
**Use Cases:**
- **Capacity Planning:** Monitor disk space usage trends
- **Performance Tuning:** Analyze cache efficiency and I/O patterns
- **Storage Optimization:** Review compression ratios and retention
- **Troubleshooting:** Diagnose DBEngine performance issues
**Storage Tiers:**
Netdata supports multiple storage tiers with different retention periods:
- **Tier 0:** High resolution (1-second), short retention
- **Tier 1:** Medium resolution, medium retention
- **Tier 2:** Low resolution, long retention
**Availability:**
This endpoint only works if DBEngine is enabled. Returns 404 if DBEngine is disabled.
**Migration:**
Modern Netdata installations should use:
- Netdata Cloud for storage monitoring across agents
- Internal metrics: `netdata.dbengine_*` charts
- System info API for aggregate statistics
**Security & Access Control:**
- 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply
- **Default Access:** Public (no authentication required)
- **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token
- **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf
- **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools
'
security:
- {}
- bearerAuth: []
responses:
'200':
description: DBEngine statistics for all tiers
content:
application/json:
schema:
type: object
description: Object with one property per tier (tier0, tier1, tier2, etc.) containing detailed statistics
additionalProperties:
type: object
description: Statistics for this specific tier
example:
tier0:
datafiles_active: 4
datafiles_total: 12
extents_total: 156789
pages_total: 8934567
compression_ratio: 3.2
disk_space_bytes: 524288000
retention_seconds: 86400
tier1:
datafiles_active: 2
datafiles_total: 6
extents_total: 45678
pages_total: 1234567
compression_ratio: 4.1
disk_space_bytes: 134217728
retention_seconds: 604800
'404':
description: DBEngine is not enabled
'503':
description: Service unavailable - Netdata not ready
/api/v1/ml_info:
get:
deprecated: true
operationId: ml_info1
tags:
- management
summary: '[DEPRECATED] Get machine learning detection information'
description: '**[DEPRECATED - Use internal metrics and Netdata Cloud for ML monitoring]**
**Machine Learning Detection Info**
Returns information about Netdata''s built-in machine learning (ML) anomaly detection system for the specified host. Netdata trains ML models on every metric to detect anomalous behavior in real-time.
**Information Provided:**
**Training Status:**
- Whether ML is enabled and trained
- Training progress and completion percentage
- Number of models trained
- Training time and resource usage
**Detection Configuration:**
- Detection sensitivity settings
- Anomaly detection thresholds
- Update frequency
- Model parameters
**Model Statistics:**
- Number of dimensions being modeled
- Model types in use (k-means, etc.)
- Model accuracy metrics
- Training data requirements
**Detection State:**
- Current anomaly detection status
- Recent anomaly counts
- Detection performance metrics
**Use Cases:**
- **ML Verification:** Confirm ML is trained and detecting anomalies
- **Troubleshooting:** Diagnose why ML isn''t detecting issues
- **Configuration:** Verify ML settings are applied correctly
- **Monitoring:** Track ML training progress on new agents
**Availability:**
This endpoint only works if:
- Netdata was compiled with ML support (`ENABLE_ML`)
- ML is enabled in configuration
- The agent has finished initial startup
Returns 503 (Service Unavailable) if ML is not compiled in or not ready.
**Machine Learning in Netdata:**
- Trains individual k-means models for every metric dimension
- Updates models continuously as new data arrives
- Detects anomalies in real-time (within seconds)
- No configuration required - works out of the box
- Models stored locally, no data sent to cloud
**Migration:**
Modern deployments should:
- Use internal metrics: `netdata.ml_*` charts
- Check Netdata Cloud for ML insights
- Use alert transitions API to see ML-based alerts
- Monitor anomaly rates via `/api/v2/data` with appropriate options
**Security & Access Control:**
- 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply
- **Default Access:** Public (no authentication required)
- **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token
- **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf
- **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools
'
security:
- {}
- bearerAuth: []
responses:
'200':
description: ML detection information for the host
content:
application/json:
schema:
type: object
description: Machine learning detection configuration and status
example:
enabled: true
trained: true
training_progress: 100
models_trained: 1247
dimensions_monitored: 1247
detection_enabled: true
anomaly_detection_running: true
'503':
description: Service unavailable - ML not compiled in, not enabled, or Netdata not ready
components:
schemas:
aclk_state:
type: object
properties:
aclk-available:
type: string
description: 'Describes whether this Agent is capable of connection to the Cloud. False means Agent has been built without ACLK component either on purpose (user choice) or due to missing dependency.
'
aclk-version:
type: integer
description: Describes which ACLK version is currently used.
protocols-supported:
type: array
description: List of supported protocols for communication with Cloud.
items:
type: string
Agent-claimed:
type: boolean
description: Informs whether this Agent has been added to a space in the cloud (User has to perform claiming). If false (user didn't perform claiming) Agent will never attempt any cloud connection.
claimed_id:
type: string
format: uuid
description: Unique ID this Agent uses to identify when connecting to cloud
online:
type: boolean
description: Informs if this Agent was connected to the cloud at the time this request has been processed.
used-cloud-protocol:
type: string
description: Informs which protocol is used to communicate with cloud
enum:
- Old
- New
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"