{ "info": { "_postman_id": "6b159918-57d6-4f1d-9efc-15fc2c18a162", "name": "Netdata agent config API", "description": "Real-time performance and health monitoring.\n\n## API Versions\n\nNetdata provides three API versions:\n- **v1**: The original API, focused on single-node operations\n- **v2**: Multi-node API with advanced grouping and aggregation capabilities\n- **v3**: The latest API version that combines v1 and v2 endpoints and may include additional features\n\n### v3 API Endpoints\n\nThe v3 API provides the current, actively maintained endpoints:\n- `/api/v3/data` - Multi-dimensional data queries\n- `/api/v3/weights` - Metric scoring/correlation\n- `/api/v3/contexts` - Context metadata\n- `/api/v3/nodes` - Node information\n- `/api/v3/q` - Full-text search\n- `/api/v3/alerts` - Alert information\n- `/api/v3/alert_transitions` - Alert state transitions\n- `/api/v3/alert_config` - Alert configuration\n- `/api/v3/functions` - Available functions\n- `/api/v3/function` - Execute functions\n- `/api/v3/info` - Agent information\n- `/api/v3/node_instances` - Node instance information\n- `/api/v3/stream_path` - Streaming topology\n- `/api/v3/versions` - Version information\n- `/api/v3/badge.svg` - Dynamic badges\n- `/api/v3/allmetrics` - Export metrics\n- `/api/v3/context` - Single context info\n- `/api/v3/variable` - Variable information\n- `/api/v3/config` - Dynamic configuration\n- `/api/v3/settings` - Agent settings\n- `/api/v3/me` - Current user information\n- `/api/v3/claim` - Agent claiming\n- Additional management and streaming endpoints\n\n**Note:** V1 and V2 APIs are deprecated and maintained for backwards compatibility only. New integrations should use V3 exclusively.\n\n\nContact Support:\n Name: Netdata Agent API\n Email: info@netdata.cloud", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "createdAt": "2026-07-28T02:17:16.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "lastUpdatedBy": "35240", "uid": "35240-6b159918-57d6-4f1d-9efc-15fc2c18a162" }, "item": [ { "name": "api", "item": [ { "name": "v3", "item": [ { "name": "config", "item": [ { "name": "Manage Netdata dynamic configuration", "id": "b2210d87-8874-406e-bb4f-c3fdd8e19b01", "protocolProfileBehavior": { "disableBodyPruning": true }, "request": { "auth": { "type": "noauth" }, "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v3/config?action=tree&path=/&id=&name=&timeout=120", "host": [ "{{baseUrl}}" ], "path": [ "api", "v3", "config" ], "query": [ { "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", "key": "action", "value": "tree" }, { "description": "Path in configuration tree when using `action=tree`.\nSpecifies which branch of the configuration hierarchy to explore.\n\n**Path Format:**\n- Root: `/`\n- Collectors: `/collectors`\n- Specific plugin: `/collectors/go.d`\n- Health: `/health`\n\n**Examples:**\n- `/` - Root level (all categories)\n- `/collectors` - All collectors\n- `/collectors/go.d` - Go collectors\n", "key": "path", "value": "/" }, { "description": "Configuration component ID using colon-separated hierarchical notation.\nRequired for most actions except `tree`.\n\n**ID Format:**\n`category:plugin:collector[:job-name]`\n\n**Examples:**\n- `collectors:go.d:prometheus` - Prometheus collector\n- `collectors:go.d:prometheus:local` - Specific Prometheus job \"local\"\n- `collectors:python.d:nginx` - Nginx Python collector\n- `health:notifications` - Health notification settings\n\n**ID Validation:**\n- Alphanumeric characters, dots, underscores, hyphens\n- Colons separate hierarchy levels\n- Invalid IDs return 400 Bad Request\n", "key": "id", "value": "" }, { "description": "Name for new job/instance when using `action=add` or `action=test`.\n\n**Name Requirements:**\n- Alphanumeric characters, dots, underscores, hyphens\n- Must be unique within the collector/plugin\n- Will be appended to `id` to form full configuration path\n\n**Examples:**\n- If `id=collectors:go.d:prometheus` and `name=my-app`\n- Full config ID becomes: `collectors:go.d:prometheus:my-app`\n\n**Invalid Names:**\n- Empty or missing (when required): Returns 400 Bad Request\n- Special characters: Returns 400 Bad Request\n- Duplicate name: May return error or override behavior depends on action\n", "key": "name", "value": "" }, { "description": "Maximum time in seconds to wait for configuration operation to complete.\n\n**Timeout Guidelines:**\n- Read operations (get, schema, tree): 10-30 seconds\n- Write operations (update, add, remove): 30-120 seconds\n- Test operations: 60-120 seconds (may involve validation checks)\n- Restart operations: 120-300 seconds (component restart time)\n\n**Minimum:** 10 seconds (enforced by code)\n**Default:** 120 seconds\n", "key": "timeout", "value": "120" } ] }, "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\u251c\u2500\u2500 collectors/\n\u2502 \u251c\u2500\u2500 plugins.d/\n\u2502 \u251c\u2500\u2500 python.d/\n\u2502 \u251c\u2500\u2500 go.d/\n\u2502 \u2514\u2500\u2500 ...\n\u251c\u2500\u2500 health/\n\u2514\u2500\u2500 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- \ud83d\udcca **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" }, "response": [ { "id": "1b79be8c-0db9-4125-b78f-29a947fad662", "name": "Configuration operation completed successfully.\n\nResponse format depends on the action:\n- `tree`: Configuration hierarchy tree\n- `get`: Current configuration JSON\n- `schema`: Configuration schema/template\n- `update`/`add`/`remove`: Success confirmation\n- ", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v3/config?action=tree&path=/&id=&name=&timeout=120", "host": [ "{{baseUrl}}" ], "path": [ "api", "v3", "config" ], "query": [ { "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", "key": "action", "value": "tree" }, { "description": "Path in configuration tree when using `action=tree`.\nSpecifies which branch of the configuration hierarchy to explore.\n\n**Path Format:**\n- Root: `/`\n- Collectors: `/collectors`\n- Specific plugin: `/collectors/go.d`\n- Health: `/health`\n\n**Examples:**\n- `/` - Root level (all categories)\n- `/collectors` - All collectors\n- `/collectors/go.d` - Go collectors\n", "key": "path", "value": "/" }, { "description": "Configuration component ID using colon-separated hierarchical notation.\nRequired for most actions except `tree`.\n\n**ID Format:**\n`category:plugin:collector[:job-name]`\n\n**Examples:**\n- `collectors:go.d:prometheus` - Prometheus collector\n- `collectors:go.d:prometheus:local` - Specific Prometheus job \"local\"\n- `collectors:python.d:nginx` - Nginx Python collector\n- `health:notifications` - Health notification settings\n\n**ID Validation:**\n- Alphanumeric characters, dots, underscores, hyphens\n- Colons separate hierarchy levels\n- Invalid IDs return 400 Bad Request\n", "key": "id", "value": "" }, { "description": "Name for new job/instance when using `action=add` or `action=test`.\n\n**Name Requirements:**\n- Alphanumeric characters, dots, underscores, hyphens\n- Must be unique within the collector/plugin\n- Will be appended to `id` to form full configuration path\n\n**Examples:**\n- If `id=collectors:go.d:prometheus` and `name=my-app`\n- Full config ID becomes: `collectors:go.d:prometheus:my-app`\n\n**Invalid Names:**\n- Empty or missing (when required): Returns 400 Bad Request\n- Special characters: Returns 400 Bad Request\n- Duplicate name: May return error or override behavior depends on action\n", "key": "name", "value": "" }, { "description": "Maximum time in seconds to wait for configuration operation to complete.\n\n**Timeout Guidelines:**\n- Read operations (get, schema, tree): 10-30 seconds\n- Write operations (update, add, remove): 30-120 seconds\n- Test operations: 60-120 seconds (may involve validation checks)\n- Restart operations: 120-300 seconds (component restart time)\n\n**Minimum:** 10 seconds (enforced by code)\n**Default:** 120 seconds\n", "key": "timeout", "value": "120" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "responseTime": null, "body": "{}", "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-1b79be8c-0db9-4125-b78f-29a947fad662" }, { "id": "e6726736-0067-401f-9a6a-ea2066776f75", "name": "Bad request. Common causes:\n- Invalid action name\n- Missing required parameters (`id`, `name`)\n- Invalid `id` or `name` format\n- Malformed request body JSON\n", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v3/config?action=tree&path=/&id=&name=&timeout=120", "host": [ "{{baseUrl}}" ], "path": [ "api", "v3", "config" ], "query": [ { "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", "key": "action", "value": "tree" }, { "description": "Path in configuration tree when using `action=tree`.\nSpecifies which branch of the configuration hierarchy to explore.\n\n**Path Format:**\n- Root: `/`\n- Collectors: `/collectors`\n- Specific plugin: `/collectors/go.d`\n- Health: `/health`\n\n**Examples:**\n- `/` - Root level (all categories)\n- `/collectors` - All collectors\n- `/collectors/go.d` - Go collectors\n", "key": "path", "value": "/" }, { "description": "Configuration component ID using colon-separated hierarchical notation.\nRequired for most actions except `tree`.\n\n**ID Format:**\n`category:plugin:collector[:job-name]`\n\n**Examples:**\n- `collectors:go.d:prometheus` - Prometheus collector\n- `collectors:go.d:prometheus:local` - Specific Prometheus job \"local\"\n- `collectors:python.d:nginx` - Nginx Python collector\n- `health:notifications` - Health notification settings\n\n**ID Validation:**\n- Alphanumeric characters, dots, underscores, hyphens\n- Colons separate hierarchy levels\n- Invalid IDs return 400 Bad Request\n", "key": "id", "value": "" }, { "description": "Name for new job/instance when using `action=add` or `action=test`.\n\n**Name Requirements:**\n- Alphanumeric characters, dots, underscores, hyphens\n- Must be unique within the collector/plugin\n- Will be appended to `id` to form full configuration path\n\n**Examples:**\n- If `id=collectors:go.d:prometheus` and `name=my-app`\n- Full config ID becomes: `collectors:go.d:prometheus:my-app`\n\n**Invalid Names:**\n- Empty or missing (when required): Returns 400 Bad Request\n- Special characters: Returns 400 Bad Request\n- Duplicate name: May return error or override behavior depends on action\n", "key": "name", "value": "" }, { "description": "Maximum time in seconds to wait for configuration operation to complete.\n\n**Timeout Guidelines:**\n- Read operations (get, schema, tree): 10-30 seconds\n- Write operations (update, add, remove): 30-120 seconds\n- Test operations: 60-120 seconds (may involve validation checks)\n- Restart operations: 120-300 seconds (component restart time)\n\n**Minimum:** 10 seconds (enforced by code)\n**Default:** 120 seconds\n", "key": "timeout", "value": "120" } ] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "text", "header": [], "cookie": [], "responseTime": null, "body": null, "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-e6726736-0067-401f-9a6a-ea2066776f75" }, { "id": "af75b4f9-734f-4edb-91e0-7df080a1866e", "name": "Forbidden. Configuration change requires higher permissions.\n", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v3/config?action=tree&path=/&id=&name=&timeout=120", "host": [ "{{baseUrl}}" ], "path": [ "api", "v3", "config" ], "query": [ { "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", "key": "action", "value": "tree" }, { "description": "Path in configuration tree when using `action=tree`.\nSpecifies which branch of the configuration hierarchy to explore.\n\n**Path Format:**\n- Root: `/`\n- Collectors: `/collectors`\n- Specific plugin: `/collectors/go.d`\n- Health: `/health`\n\n**Examples:**\n- `/` - Root level (all categories)\n- `/collectors` - All collectors\n- `/collectors/go.d` - Go collectors\n", "key": "path", "value": "/" }, { "description": "Configuration component ID using colon-separated hierarchical notation.\nRequired for most actions except `tree`.\n\n**ID Format:**\n`category:plugin:collector[:job-name]`\n\n**Examples:**\n- `collectors:go.d:prometheus` - Prometheus collector\n- `collectors:go.d:prometheus:local` - Specific Prometheus job \"local\"\n- `collectors:python.d:nginx` - Nginx Python collector\n- `health:notifications` - Health notification settings\n\n**ID Validation:**\n- Alphanumeric characters, dots, underscores, hyphens\n- Colons separate hierarchy levels\n- Invalid IDs return 400 Bad Request\n", "key": "id", "value": "" }, { "description": "Name for new job/instance when using `action=add` or `action=test`.\n\n**Name Requirements:**\n- Alphanumeric characters, dots, underscores, hyphens\n- Must be unique within the collector/plugin\n- Will be appended to `id` to form full configuration path\n\n**Examples:**\n- If `id=collectors:go.d:prometheus` and `name=my-app`\n- Full config ID becomes: `collectors:go.d:prometheus:my-app`\n\n**Invalid Names:**\n- Empty or missing (when required): Returns 400 Bad Request\n- Special characters: Returns 400 Bad Request\n- Duplicate name: May return error or override behavior depends on action\n", "key": "name", "value": "" }, { "description": "Maximum time in seconds to wait for configuration operation to complete.\n\n**Timeout Guidelines:**\n- Read operations (get, schema, tree): 10-30 seconds\n- Write operations (update, add, remove): 30-120 seconds\n- Test operations: 60-120 seconds (may involve validation checks)\n- Restart operations: 120-300 seconds (component restart time)\n\n**Minimum:** 10 seconds (enforced by code)\n**Default:** 120 seconds\n", "key": "timeout", "value": "120" } ] } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "text", "header": [], "cookie": [], "responseTime": null, "body": null, "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-af75b4f9-734f-4edb-91e0-7df080a1866e" }, { "id": "be396cbf-52dd-4c43-9dda-89b4275cb763", "name": "Configuration component not found. The specified `id` does not exist.\n", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v3/config?action=tree&path=/&id=&name=&timeout=120", "host": [ "{{baseUrl}}" ], "path": [ "api", "v3", "config" ], "query": [ { "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", "key": "action", "value": "tree" }, { "description": "Path in configuration tree when using `action=tree`.\nSpecifies which branch of the configuration hierarchy to explore.\n\n**Path Format:**\n- Root: `/`\n- Collectors: `/collectors`\n- Specific plugin: `/collectors/go.d`\n- Health: `/health`\n\n**Examples:**\n- `/` - Root level (all categories)\n- `/collectors` - All collectors\n- `/collectors/go.d` - Go collectors\n", "key": "path", "value": "/" }, { "description": "Configuration component ID using colon-separated hierarchical notation.\nRequired for most actions except `tree`.\n\n**ID Format:**\n`category:plugin:collector[:job-name]`\n\n**Examples:**\n- `collectors:go.d:prometheus` - Prometheus collector\n- `collectors:go.d:prometheus:local` - Specific Prometheus job \"local\"\n- `collectors:python.d:nginx` - Nginx Python collector\n- `health:notifications` - Health notification settings\n\n**ID Validation:**\n- Alphanumeric characters, dots, underscores, hyphens\n- Colons separate hierarchy levels\n- Invalid IDs return 400 Bad Request\n", "key": "id", "value": "" }, { "description": "Name for new job/instance when using `action=add` or `action=test`.\n\n**Name Requirements:**\n- Alphanumeric characters, dots, underscores, hyphens\n- Must be unique within the collector/plugin\n- Will be appended to `id` to form full configuration path\n\n**Examples:**\n- If `id=collectors:go.d:prometheus` and `name=my-app`\n- Full config ID becomes: `collectors:go.d:prometheus:my-app`\n\n**Invalid Names:**\n- Empty or missing (when required): Returns 400 Bad Request\n- Special characters: Returns 400 Bad Request\n- Duplicate name: May return error or override behavior depends on action\n", "key": "name", "value": "" }, { "description": "Maximum time in seconds to wait for configuration operation to complete.\n\n**Timeout Guidelines:**\n- Read operations (get, schema, tree): 10-30 seconds\n- Write operations (update, add, remove): 30-120 seconds\n- Test operations: 60-120 seconds (may involve validation checks)\n- Restart operations: 120-300 seconds (component restart time)\n\n**Minimum:** 10 seconds (enforced by code)\n**Default:** 120 seconds\n", "key": "timeout", "value": "120" } ] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "text", "header": [], "cookie": [], "responseTime": null, "body": null, "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-be396cbf-52dd-4c43-9dda-89b4275cb763" }, { "id": "41f2bc10-c4da-4d16-a771-62e78ee13936", "name": "Internal server error during configuration operation.", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v3/config?action=tree&path=/&id=&name=&timeout=120", "host": [ "{{baseUrl}}" ], "path": [ "api", "v3", "config" ], "query": [ { "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", "key": "action", "value": "tree" }, { "description": "Path in configuration tree when using `action=tree`.\nSpecifies which branch of the configuration hierarchy to explore.\n\n**Path Format:**\n- Root: `/`\n- Collectors: `/collectors`\n- Specific plugin: `/collectors/go.d`\n- Health: `/health`\n\n**Examples:**\n- `/` - Root level (all categories)\n- `/collectors` - All collectors\n- `/collectors/go.d` - Go collectors\n", "key": "path", "value": "/" }, { "description": "Configuration component ID using colon-separated hierarchical notation.\nRequired for most actions except `tree`.\n\n**ID Format:**\n`category:plugin:collector[:job-name]`\n\n**Examples:**\n- `collectors:go.d:prometheus` - Prometheus collector\n- `collectors:go.d:prometheus:local` - Specific Prometheus job \"local\"\n- `collectors:python.d:nginx` - Nginx Python collector\n- `health:notifications` - Health notification settings\n\n**ID Validation:**\n- Alphanumeric characters, dots, underscores, hyphens\n- Colons separate hierarchy levels\n- Invalid IDs return 400 Bad Request\n", "key": "id", "value": "" }, { "description": "Name for new job/instance when using `action=add` or `action=test`.\n\n**Name Requirements:**\n- Alphanumeric characters, dots, underscores, hyphens\n- Must be unique within the collector/plugin\n- Will be appended to `id` to form full configuration path\n\n**Examples:**\n- If `id=collectors:go.d:prometheus` and `name=my-app`\n- Full config ID becomes: `collectors:go.d:prometheus:my-app`\n\n**Invalid Names:**\n- Empty or missing (when required): Returns 400 Bad Request\n- Special characters: Returns 400 Bad Request\n- Duplicate name: May return error or override behavior depends on action\n", "key": "name", "value": "" }, { "description": "Maximum time in seconds to wait for configuration operation to complete.\n\n**Timeout Guidelines:**\n- Read operations (get, schema, tree): 10-30 seconds\n- Write operations (update, add, remove): 30-120 seconds\n- Test operations: 60-120 seconds (may involve validation checks)\n- Restart operations: 120-300 seconds (component restart time)\n\n**Minimum:** 10 seconds (enforced by code)\n**Default:** 120 seconds\n", "key": "timeout", "value": "120" } ] } }, "status": "Internal Server Error", "code": 500, "_postman_previewlanguage": "text", "header": [], "cookie": [], "responseTime": null, "body": null, "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-41f2bc10-c4da-4d16-a771-62e78ee13936" }, { "id": "0462461b-3fee-484c-be82-c18da32a322a", "name": "Configuration operation timeout.", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v3/config?action=tree&path=/&id=&name=&timeout=120", "host": [ "{{baseUrl}}" ], "path": [ "api", "v3", "config" ], "query": [ { "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", "key": "action", "value": "tree" }, { "description": "Path in configuration tree when using `action=tree`.\nSpecifies which branch of the configuration hierarchy to explore.\n\n**Path Format:**\n- Root: `/`\n- Collectors: `/collectors`\n- Specific plugin: `/collectors/go.d`\n- Health: `/health`\n\n**Examples:**\n- `/` - Root level (all categories)\n- `/collectors` - All collectors\n- `/collectors/go.d` - Go collectors\n", "key": "path", "value": "/" }, { "description": "Configuration component ID using colon-separated hierarchical notation.\nRequired for most actions except `tree`.\n\n**ID Format:**\n`category:plugin:collector[:job-name]`\n\n**Examples:**\n- `collectors:go.d:prometheus` - Prometheus collector\n- `collectors:go.d:prometheus:local` - Specific Prometheus job \"local\"\n- `collectors:python.d:nginx` - Nginx Python collector\n- `health:notifications` - Health notification settings\n\n**ID Validation:**\n- Alphanumeric characters, dots, underscores, hyphens\n- Colons separate hierarchy levels\n- Invalid IDs return 400 Bad Request\n", "key": "id", "value": "" }, { "description": "Name for new job/instance when using `action=add` or `action=test`.\n\n**Name Requirements:**\n- Alphanumeric characters, dots, underscores, hyphens\n- Must be unique within the collector/plugin\n- Will be appended to `id` to form full configuration path\n\n**Examples:**\n- If `id=collectors:go.d:prometheus` and `name=my-app`\n- Full config ID becomes: `collectors:go.d:prometheus:my-app`\n\n**Invalid Names:**\n- Empty or missing (when required): Returns 400 Bad Request\n- Special characters: Returns 400 Bad Request\n- Duplicate name: May return error or override behavior depends on action\n", "key": "name", "value": "" }, { "description": "Maximum time in seconds to wait for configuration operation to complete.\n\n**Timeout Guidelines:**\n- Read operations (get, schema, tree): 10-30 seconds\n- Write operations (update, add, remove): 30-120 seconds\n- Test operations: 60-120 seconds (may involve validation checks)\n- Restart operations: 120-300 seconds (component restart time)\n\n**Minimum:** 10 seconds (enforced by code)\n**Default:** 120 seconds\n", "key": "timeout", "value": "120" } ] } }, "status": "Gateway Timeout", "code": 504, "_postman_previewlanguage": "text", "header": [], "cookie": [], "responseTime": null, "body": null, "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-0462461b-3fee-484c-be82-c18da32a322a" } ], "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-b2210d87-8874-406e-bb4f-c3fdd8e19b01" }, { "name": "Manage Netdata configuration with request body data", "id": "65ea2010-d0ea-493a-bd65-17a3901ba6f0", "protocolProfileBehavior": { "disableBodyPruning": true }, "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "url": { "raw": "{{baseUrl}}/api/v3/config?action=tree&path=/&id=&name=&timeout=120", "host": [ "{{baseUrl}}" ], "path": [ "api", "v3", "config" ], "query": [ { "description": "Configuration action to perform (see GET method for details)", "key": "action", "value": "tree" }, { "description": "Path in configuration tree (see GET method for details)", "key": "path", "value": "/" }, { "description": "Configuration component ID (see GET method for details)", "key": "id", "value": "" }, { "description": "Name for new job/instance (see GET method for details)", "key": "name", "value": "" }, { "description": "Maximum timeout in seconds (see GET method for details)", "key": "timeout", "value": "120" } ] }, "description": "Same as GET /api/v3/config, but allows passing configuration data via request body\nfor actions like `update`, `add`, and `test`.\n\nUse this method when:\n- Updating existing configuration (`action=update`)\n- Adding new jobs/instances (`action=add`)\n- Testing configuration before applying (`action=test`)\n\nSee GET /api/v3/config for complete documentation on actions, parameters, and responses.\n" }, "response": [ { "id": "6477271b-7fb4-486e-93cc-866ae166a748", "name": "Configuration operation completed successfully (see GET method for response details)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "url": { "raw": "{{baseUrl}}/api/v3/config?action=tree&path=/&id=&name=&timeout=120", "host": [ "{{baseUrl}}" ], "path": [ "api", "v3", "config" ], "query": [ { "description": "Configuration action to perform (see GET method for details)", "key": "action", "value": "tree" }, { "description": "Path in configuration tree (see GET method for details)", "key": "path", "value": "/" }, { "description": "Configuration component ID (see GET method for details)", "key": "id", "value": "" }, { "description": "Name for new job/instance (see GET method for details)", "key": "name", "value": "" }, { "description": "Maximum timeout in seconds (see GET method for details)", "key": "timeout", "value": "120" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "responseTime": null, "body": "{}", "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-6477271b-7fb4-486e-93cc-866ae166a748" }, { "id": "fc0923c1-b03a-4b1b-b191-3bcfbbaacc5d", "name": "Bad request (see GET method for details)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "url": { "raw": "{{baseUrl}}/api/v3/config?action=tree&path=/&id=&name=&timeout=120", "host": [ "{{baseUrl}}" ], "path": [ "api", "v3", "config" ], "query": [ { "description": "Configuration action to perform (see GET method for details)", "key": "action", "value": "tree" }, { "description": "Path in configuration tree (see GET method for details)", "key": "path", "value": "/" }, { "description": "Configuration component ID (see GET method for details)", "key": "id", "value": "" }, { "description": "Name for new job/instance (see GET method for details)", "key": "name", "value": "" }, { "description": "Maximum timeout in seconds (see GET method for details)", "key": "timeout", "value": "120" } ] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "text", "header": [], "cookie": [], "responseTime": null, "body": null, "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-fc0923c1-b03a-4b1b-b191-3bcfbbaacc5d" }, { "id": "c338a376-894d-4f6d-bba2-0392151f5c97", "name": "Forbidden (see GET method for details)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "url": { "raw": "{{baseUrl}}/api/v3/config?action=tree&path=/&id=&name=&timeout=120", "host": [ "{{baseUrl}}" ], "path": [ "api", "v3", "config" ], "query": [ { "description": "Configuration action to perform (see GET method for details)", "key": "action", "value": "tree" }, { "description": "Path in configuration tree (see GET method for details)", "key": "path", "value": "/" }, { "description": "Configuration component ID (see GET method for details)", "key": "id", "value": "" }, { "description": "Name for new job/instance (see GET method for details)", "key": "name", "value": "" }, { "description": "Maximum timeout in seconds (see GET method for details)", "key": "timeout", "value": "120" } ] } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "text", "header": [], "cookie": [], "responseTime": null, "body": null, "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-c338a376-894d-4f6d-bba2-0392151f5c97" }, { "id": "cf9d250f-0a16-44c2-81af-d5be08550cc7", "name": "Configuration component not found (see GET method for details)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "url": { "raw": "{{baseUrl}}/api/v3/config?action=tree&path=/&id=&name=&timeout=120", "host": [ "{{baseUrl}}" ], "path": [ "api", "v3", "config" ], "query": [ { "description": "Configuration action to perform (see GET method for details)", "key": "action", "value": "tree" }, { "description": "Path in configuration tree (see GET method for details)", "key": "path", "value": "/" }, { "description": "Configuration component ID (see GET method for details)", "key": "id", "value": "" }, { "description": "Name for new job/instance (see GET method for details)", "key": "name", "value": "" }, { "description": "Maximum timeout in seconds (see GET method for details)", "key": "timeout", "value": "120" } ] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "text", "header": [], "cookie": [], "responseTime": null, "body": null, "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-cf9d250f-0a16-44c2-81af-d5be08550cc7" }, { "id": "244a4639-eda8-467e-8d63-38d7fd25fa90", "name": "Internal server error (see GET method for details)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "url": { "raw": "{{baseUrl}}/api/v3/config?action=tree&path=/&id=&name=&timeout=120", "host": [ "{{baseUrl}}" ], "path": [ "api", "v3", "config" ], "query": [ { "description": "Configuration action to perform (see GET method for details)", "key": "action", "value": "tree" }, { "description": "Path in configuration tree (see GET method for details)", "key": "path", "value": "/" }, { "description": "Configuration component ID (see GET method for details)", "key": "id", "value": "" }, { "description": "Name for new job/instance (see GET method for details)", "key": "name", "value": "" }, { "description": "Maximum timeout in seconds (see GET method for details)", "key": "timeout", "value": "120" } ] } }, "status": "Internal Server Error", "code": 500, "_postman_previewlanguage": "text", "header": [], "cookie": [], "responseTime": null, "body": null, "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-244a4639-eda8-467e-8d63-38d7fd25fa90" }, { "id": "cafbed59-6e5e-4856-8f80-1f4d1d84a2bc", "name": "Configuration operation timeout (see GET method for details)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "url": { "raw": "{{baseUrl}}/api/v3/config?action=tree&path=/&id=&name=&timeout=120", "host": [ "{{baseUrl}}" ], "path": [ "api", "v3", "config" ], "query": [ { "description": "Configuration action to perform (see GET method for details)", "key": "action", "value": "tree" }, { "description": "Path in configuration tree (see GET method for details)", "key": "path", "value": "/" }, { "description": "Configuration component ID (see GET method for details)", "key": "id", "value": "" }, { "description": "Name for new job/instance (see GET method for details)", "key": "name", "value": "" }, { "description": "Maximum timeout in seconds (see GET method for details)", "key": "timeout", "value": "120" } ] } }, "status": "Gateway Timeout", "code": 504, "_postman_previewlanguage": "text", "header": [], "cookie": [], "responseTime": null, "body": null, "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-cafbed59-6e5e-4856-8f80-1f4d1d84a2bc" } ], "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-65ea2010-d0ea-493a-bd65-17a3901ba6f0" } ], "id": "aa07d47f-6b3a-484b-b8b0-3ef626ac1447", "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-aa07d47f-6b3a-484b-b8b0-3ef626ac1447" } ], "id": "66ac1035-03a5-4ab0-a73e-9809a4e78939", "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-66ac1035-03a5-4ab0-a73e-9809a4e78939" } ], "id": "24b35425-896e-4a93-b3bf-7f5192959972", "createdAt": "2026-07-28T02:17:17.000Z", "updatedAt": "2026-07-28T02:17:17.000Z", "uid": "35240-24b35425-896e-4a93-b3bf-7f5192959972" } ], "variable": [ { "key": "baseUrl", "value": "https://registry.my-netdata.io" } ] }