The config API from Netdata — 1 operation(s) for config.
openapi: 3.0.0
info:
title: Netdata agent config 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: config
paths:
/api/v3/config:
get:
operationId: config3
tags:
- config
summary: Manage Netdata dynamic configuration
description: "Provides access to Netdata's dynamic configuration system, allowing retrieval, modification,\nand management of configuration across plugins and data collectors.\n\n**Dynamic Configuration System:**\nNetdata's dyncfg system allows runtime configuration management without restarting the agent:\n- **View configuration tree**: Browse all configurable components\n- **Get current config**: Retrieve active configuration for any component\n- **Update configuration**: Modify settings on-the-fly\n- **Add/remove jobs**: Manage data collection jobs dynamically\n- **Enable/disable**: Toggle components without editing files\n- **Test configuration**: Validate changes before applying\n\n**Configuration Hierarchy:**\n```\n/ (root)\n├── collectors/\n│ ├── plugins.d/\n│ ├── python.d/\n│ ├── go.d/\n│ └── ...\n├── health/\n└── streaming/\n```\n\n**Common Actions:**\n- `tree` - Browse configuration hierarchy\n- `get` - Retrieve current configuration\n- `schema` - Get configuration schema/template\n- `update` - Modify existing configuration\n- `add` - Create new job/instance\n- `remove` - Delete job/instance\n- `enable` - Activate disabled component\n- `disable` - Deactivate component\n- `test` - Validate configuration without applying\n- `restart` - Restart component with new config\n- `userconfig` - Get user-editable configuration\n\n**Use Cases:**\n- **Configuration management**: Centrally manage agent configuration\n- **Job provisioning**: Add new data collection jobs without restart\n- **A/B testing**: Test configuration changes before deployment\n- **Automation**: Integrate with configuration management tools\n- **Troubleshooting**: View and modify settings for debugging\n\n**Common Usage Patterns:**\n\n1. **Browse configuration tree:**\n ```\n /api/v3/config?action=tree&path=/\n ```\n\n2. **Get configuration for a specific component:**\n ```\n /api/v3/config?action=get&id=collectors:go.d:prometheus\n ```\n\n3. **Get configuration schema:**\n ```\n /api/v3/config?action=schema&id=collectors:go.d:prometheus\n ```\n\n4. **Add new data collection job:**\n ```\n POST /api/v3/config?action=add&id=collectors:go.d:prometheus&name=my-app\n Content-Type: application/json\n\n {\n \"url\": \"http://my-app:9090/metrics\",\n \"update_every\": 10\n }\n ```\n\n5. **Update existing configuration:**\n ```\n POST /api/v3/config?action=update&id=collectors:go.d:prometheus:my-app\n Content-Type: application/json\n\n {\n \"update_every\": 5\n }\n ```\n\n6. **Test configuration before applying:**\n ```\n POST /api/v3/config?action=test&id=collectors:go.d:prometheus&name=test-job\n [configuration JSON]\n ```\n\n**ID Format:**\nConfiguration IDs use colon-separated hierarchical paths:\n- `collectors:go.d:prometheus` - Plugin/collector level\n- `collectors:go.d:prometheus:job-name` - Specific job/instance\n- `health:notifications` - Health alert notifications\n\n**Request Body:**\nFor `update`, `add`, and `test` actions, provide configuration as JSON in request body.\nUse `schema` action to get the expected configuration structure.\n\n**Security:**\n- Configuration changes require appropriate permissions\n- Some actions may be restricted by ACL\n- Changes are logged for audit trail\n\n**Security & Access Control:**\n- \U0001F4CA **Public Data API** - Bearer token optional, IP-based ACL restrictions apply\n- **Default Access:** Public (no authentication required)\n- **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token\n- **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf\n- **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools\n"
security:
- {}
- bearerAuth: []
parameters:
- name: action
in: query
required: false
description: "Configuration action to perform. Different actions require different additional parameters.\n\n**Available Actions:**\n\n- **`tree`** (default): Browse configuration hierarchy\n - Additional params: `path` (optional, default \"/\"), `id` (optional)\n - Returns: Tree structure of configurable components\n\n- **`get`**: Retrieve current configuration\n - Required params: `id`\n - Returns: Current active configuration\n\n- **`schema`**: Get configuration schema/template\n - Required params: `id`\n - Returns: Schema defining valid configuration structure\n\n- **`update`**: Modify existing configuration\n - Required params: `id`\n - Request body: JSON with configuration changes\n - Returns: Success/error status\n\n- **`add`**: Create new job/instance\n - Required params: `id`, `name`\n - Request body: JSON with initial configuration\n - Returns: Success/error status\n\n- **`remove`**: Delete job/instance\n - Required params: `id`\n - Returns: Success/error status\n\n- **`enable`**: Activate disabled component\n - Required params: `id`\n - Returns: Success/error status\n\n- **`disable`**: Deactivate component without removing\n - Required params: `id`\n - Returns: Success/error status\n\n- **`test`**: Validate configuration without applying\n - Required params: `id`, `name`\n - Request body: JSON with configuration to test\n - Returns: Validation results\n\n- **`restart`**: Restart component with new configuration\n - Required params: `id`\n - Returns: Success/error status\n\n- **`userconfig`**: Get user-editable configuration file\n - Required params: `id`\n - Returns: Configuration in user-editable format\n"
schema:
type: string
enum:
- tree
- get
- schema
- update
- add
- remove
- enable
- disable
- test
- restart
- userconfig
default: tree
example: tree
- name: path
in: query
required: false
description: 'Path in configuration tree when using `action=tree`.
Specifies which branch of the configuration hierarchy to explore.
**Path Format:**
- Root: `/`
- Collectors: `/collectors`
- Specific plugin: `/collectors/go.d`
- Health: `/health`
**Examples:**
- `/` - Root level (all categories)
- `/collectors` - All collectors
- `/collectors/go.d` - Go collectors
'
schema:
type: string
default: /
example: /collectors
- name: id
in: query
required: false
description: 'Configuration component ID using colon-separated hierarchical notation.
Required for most actions except `tree`.
**ID Format:**
`category:plugin:collector[:job-name]`
**Examples:**
- `collectors:go.d:prometheus` - Prometheus collector
- `collectors:go.d:prometheus:local` - Specific Prometheus job "local"
- `collectors:python.d:nginx` - Nginx Python collector
- `health:notifications` - Health notification settings
**ID Validation:**
- Alphanumeric characters, dots, underscores, hyphens
- Colons separate hierarchy levels
- Invalid IDs return 400 Bad Request
'
schema:
type: string
example: collectors:go.d:prometheus
- name: name
in: query
required: false
description: 'Name for new job/instance when using `action=add` or `action=test`.
**Name Requirements:**
- Alphanumeric characters, dots, underscores, hyphens
- Must be unique within the collector/plugin
- Will be appended to `id` to form full configuration path
**Examples:**
- If `id=collectors:go.d:prometheus` and `name=my-app`
- Full config ID becomes: `collectors:go.d:prometheus:my-app`
**Invalid Names:**
- Empty or missing (when required): Returns 400 Bad Request
- Special characters: Returns 400 Bad Request
- Duplicate name: May return error or override behavior depends on action
'
schema:
type: string
example: my-app
- name: timeout
in: query
required: false
description: 'Maximum time in seconds to wait for configuration operation to complete.
**Timeout Guidelines:**
- Read operations (get, schema, tree): 10-30 seconds
- Write operations (update, add, remove): 30-120 seconds
- Test operations: 60-120 seconds (may involve validation checks)
- Restart operations: 120-300 seconds (component restart time)
**Minimum:** 10 seconds (enforced by code)
**Default:** 120 seconds
'
schema:
type: integer
minimum: 10
maximum: 3600
default: 120
example: 60
responses:
'200':
description: 'Configuration operation completed successfully.
Response format depends on the action:
- `tree`: Configuration hierarchy tree
- `get`: Current configuration JSON
- `schema`: Configuration schema/template
- `update`/`add`/`remove`: Success confirmation
- `test`: Validation results
'
content:
application/json:
schema:
type: object
description: Action-specific response data
'400':
description: 'Bad request. Common causes:
- Invalid action name
- Missing required parameters (`id`, `name`)
- Invalid `id` or `name` format
- Malformed request body JSON
'
'403':
description: 'Forbidden. Configuration change requires higher permissions.
'
'404':
description: 'Configuration component not found. The specified `id` does not exist.
'
'500':
description: Internal server error during configuration operation.
'504':
description: Configuration operation timeout.
post:
operationId: config3_post
tags:
- config
summary: Manage Netdata configuration with request body data
description: 'Same as GET /api/v3/config, but allows passing configuration data via request body
for actions like `update`, `add`, and `test`.
Use this method when:
- Updating existing configuration (`action=update`)
- Adding new jobs/instances (`action=add`)
- Testing configuration before applying (`action=test`)
See GET /api/v3/config for complete documentation on actions, parameters, and responses.
'
security:
- {}
- bearerAuth: []
parameters:
- name: action
in: query
required: false
description: Configuration action to perform (see GET method for details)
schema:
type: string
enum:
- tree
- get
- schema
- update
- add
- remove
- enable
- disable
- test
- restart
- userconfig
default: tree
example: update
- name: path
in: query
required: false
description: Path in configuration tree (see GET method for details)
schema:
type: string
default: /
example: /collectors
- name: id
in: query
required: false
description: Configuration component ID (see GET method for details)
schema:
type: string
example: collectors:go.d:prometheus
- name: name
in: query
required: false
description: Name for new job/instance (see GET method for details)
schema:
type: string
example: my-app
- name: timeout
in: query
required: false
description: Maximum timeout in seconds (see GET method for details)
schema:
type: integer
minimum: 10
maximum: 3600
default: 120
example: 60
requestBody:
description: "Configuration data for `update`, `add`, and `test` actions.\n\n**Format:**\n- Content-Type: application/json\n- Structure depends on the specific configuration component\n- Use `action=schema` to get the expected structure\n\n**Example for adding Prometheus job:**\n```json\n{\n \"url\": \"http://localhost:9090/metrics\",\n \"update_every\": 10,\n \"autodetection_retry\": 0\n}\n```\n\n**Example for updating existing config:**\n```json\n{\n \"update_every\": 5,\n \"timeout\": 30\n}\n```\n"
required: false
content:
application/json:
schema:
type: object
description: Configuration-specific data structure
responses:
'200':
description: Configuration operation completed successfully (see GET method for response details)
content:
application/json:
schema:
type: object
'400':
description: Bad request (see GET method for details)
'403':
description: Forbidden (see GET method for details)
'404':
description: Configuration component not found (see GET method for details)
'500':
description: Internal server error (see GET method for details)
'504':
description: Configuration operation timeout (see GET method for details)
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"