Query Netdata Dynamic Configuration (DynCfg)

This guide is part of the query-netdata-cloud skill. Read the SKILL.md prerequisites first.

DynCfg is Netdata's dynamic-configuration system. Every plugin / collector / module that participates registers configuration objects which the user can list, view, edit, enable, disable, add, remove, test, restart, and export -- through a single REST surface distinct from the Function-call surface. Internally DynCfg is implemented on top of Functions, but it has its own dedicated API endpoint. Don't confuse the two: function-call paths (/api/v2/nodes/{nodeID}/function?function=...) DO NOT operate on configuration.

Canonical references (authoritative; read these for full detail):

Mandatory Requirements (READ FIRST)

1. Provide actionable instructions. Each answer ends in a runnable curl command.
2. Never request credentials. Use YOUR_API_TOKEN, YOUR_NODE_UUID, etc. placeholders.
3. Read actions are GET; write actions are POST. Cloud's permission gate is PermissionFunctionExecPrivileged for the write paths. A read-only token cannot mutate configuration.
4. The action=tree listing is the entry point. Always start there; the IDs returned are the inputs to all other actions.

Endpoints

Cloud-proxied (preferred)

Cloud-side route registration: cloud-charts-service/http/http.go:150-151.

Direct-agent (fallback)

Same shape, served by the agent itself: http://<agent>:19999/host/{nodeID}/api/v3/config?.... The agent also accepts /api/v1/config for backwards compatibility -- both paths use the same handler at <repo>/src/web/api/v1/api_v1_config.c.

For direct-agent calls, X-Netdata-Auth: Bearer <agent-bearer> is required when the agent is bearer-protected. See the query-netdata-agents skill for the bearer mint/cache flow.

Query parameters

The handler at <repo>/src/web/api/v1/api_v1_config.c:5-80 accepts these query parameters:

The body of a POST carries the payload for write actions (the configuration JSON to apply, or the test input for test).

DynCfg actions

From <repo>/src/daemon/dyncfg/README.md and the agent's command enum:

DynCfg response codes

DynCfg uses HTTP-like codes verified against <repo>/src/daemon/dyncfg/README.md:

Configuration ID structure

Configuration IDs follow a colon-separated hierarchy (<repo>/src/daemon/dyncfg/README.md):

component:category:name
component:template_name:job_name

Examples (verified live -- agent-events node returns these under tree):

• /collectors/go.d/Jobs -- the go.d.plugin Jobs tree
• /collectors/go.d/ServiceDiscovery
• /collectors/go.d/Vnodes
• /collectors/ibm.d/Jobs
• /collectors/ibm.d/Vnodes
• /health/alerts/prototypes -- alert prototypes
• /logs/systemd-journal -- systemd-journal collector configs

Each tree entry contains configuration objects with their own ids (e.g. health:alert:prototype:ram_usage, go.d:nginx:local_server).

Templates vs Jobs

• Template id: component:template_name. Templates DEFINE the schema for jobs. They cannot be updated but can be add'd to.
• Job id: component:template_name:job_name. The portion before the last colon must match an existing template id.
• Single id: component:name. A standalone configuration object that is neither template nor job.

Examples

Example 1: list every configuration object on a node

TOKEN="YOUR_API_TOKEN"
NODE="YOUR_NODE_UUID"

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v2/nodes/$NODE/config?action=tree&path=/"

Response top level (verified live): {agent, attention, tree, version}. The tree is keyed by configuration path; each entry lists per-object ids, types, statuses, supported commands, and sources.

Example 2: get the JSON Schema for an alert prototype

TOKEN="YOUR_API_TOKEN"
NODE="YOUR_NODE_UUID"
ID="health:alert:prototype:ram_usage"

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v2/nodes/$NODE/config?action=schema&id=$(printf %s "$ID" | jq -sRr @uri)"

The schema describes which fields the configuration accepts and is the basis for any UI form. Use this before constructing an update payload.

Example 3: read the current value of a configuration

TOKEN="YOUR_API_TOKEN"
NODE="YOUR_NODE_UUID"
ID="health:alert:prototype:ram_usage"

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v2/nodes/$NODE/config?action=get&id=$(printf %s "$ID" | jq -sRr @uri)"

Example 4: add a new go.d.plugin job to a template

TOKEN="YOUR_API_TOKEN"
NODE="YOUR_NODE_UUID"
TPL_ID="go.d:nginx"
JOB_NAME="local_server"

read -r -d '' PAYLOAD <<'EOF'
{
  "url":             "http://127.0.0.1:80/stub_status",
  "update_every":    5,
  "timeout":         2
}
EOF

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v2/nodes/$NODE/config?action=add&id=$(printf %s "$TPL_ID" | jq -sRr @uri)&name=$JOB_NAME" \
  -d "$PAYLOAD"

Example 5: test a configuration without applying it

TOKEN="YOUR_API_TOKEN"
NODE="YOUR_NODE_UUID"
TPL_ID="go.d:nginx"
JOB_NAME="local_server"

read -r -d '' PAYLOAD <<'EOF'
{
  "url":          "http://127.0.0.1:80/stub_status",
  "update_every": 5
}
EOF

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v2/nodes/$NODE/config?action=test&id=$(printf %s "$TPL_ID" | jq -sRr @uri)&name=$JOB_NAME" \
  -d "$PAYLOAD"

A successful response means the resource accepted its supported test, not necessarily that the configuration will work in production. Inspect the response message: some resources provide only validation, while others run a resource-specific operational check. For service discovery, an empty successful message means every configured discoverer completed its operational test; an explicit validation-only message means no operational check was available. The test does NOT make the change persistent.

Example 6: enable / disable a configuration

TOKEN="YOUR_API_TOKEN"
NODE="YOUR_NODE_UUID"
ID="go.d:nginx:local_server"

# Enable
curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v2/nodes/$NODE/config?action=enable&id=$(printf %s "$ID" | jq -sRr @uri)"

# Disable
curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v2/nodes/$NODE/config?action=disable&id=$(printf %s "$ID" | jq -sRr @uri)"

Example 7: remove a dyncfg-created job

TOKEN="YOUR_API_TOKEN"
NODE="YOUR_NODE_UUID"
ID="go.d:nginx:local_server"

curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v2/nodes/$NODE/config?action=remove&id=$(printf %s "$ID" | jq -sRr @uri)"

Only objects whose source_type == DYNCFG_SOURCE_TYPE_DYNCFG (i.e. created via DynCfg, not from user files or internally) can be removed.

Example 8: get a job's user-friendly configuration (for conf-file export)

TOKEN="YOUR_API_TOKEN"
NODE="YOUR_NODE_UUID"
ID="go.d:nginx"
JOB_NAME="local_server"

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v2/nodes/$NODE/config?action=userconfig&id=$(printf %s "$ID" | jq -sRr @uri)&name=$JOB_NAME"

Source types

A configuration object's source_type (verified in <repo>/src/daemon/dyncfg/README.md) determines what's allowed:

Direct-agent reload note

There is no REST endpoint to reload /etc/netdata/health.d/*.conf files -- DynCfg manages dynamic configuration objects, not raw file reload. To reload static health/alert files, send SIGHUP to the agent process or use the dyncfg restart action on the relevant configuration object.

Sensitive data

DynCfg responses can include credentials embedded in collector job configurations (database URIs, API tokens used by collectors, etc.). Treat raw responses as production-sensitive:

• Direct working output to <repo>/.local/audits/... (gitignored).
• Never paste raw get / userconfig payloads into committed files.
• See <repo>/.agents/sensitive-data-discipline.md for the full rule.