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"