| 1 | # Query agent DynCfg directly |
| 2 | |
| 3 | This guide is part of the [`query-netdata-agents`](./SKILL.md) skill. |
| 4 | Read [SKILL.md](./SKILL.md#prerequisites) first. |
| 5 | |
| 6 | For the full DynCfg surface (actions, id structure, |
| 7 | templates/jobs, source types, response codes, schema flow), see |
| 8 | [../query-netdata-cloud/query-dyncfg.md](../query-netdata-cloud/query-dyncfg.md). |
| 9 | |
| 10 | Direct-agent uses the same query parameters and the same payloads |
| 11 | as the Cloud-proxied path. The agent's handler at |
| 12 | `<repo>/src/web/api/v1/api_v1_config.c` is the canonical |
| 13 | implementation; both `/api/v1/config` and `/api/v3/config` route |
| 14 | to it. Prefer v3. |
| 15 | |
| 16 | --- |
| 17 | |
| 18 | ## Endpoint (agent v3) |
| 19 | |
| 20 | | Method | Path | Purpose | |
| 21 | |---|---|---| |
| 22 | | `GET` | `/api/v3/config?action=tree&path=/` | List configuration objects | |
| 23 | | `GET` | `/api/v3/config?action=<read>&id=<id>[&name=<name>]` | Read a configuration | |
| 24 | | `POST` | `/api/v3/config?action=<write>&id=<id>[&name=<name>]` | Mutate a configuration (body = config JSON) | |
| 25 | |
| 26 | ## Use the wrapper |
| 27 | |
| 28 | ```bash |
| 29 | source "$(git rev-parse --show-toplevel)/.agents/skills/query-netdata-agents/scripts/_lib.sh" |
| 30 | agents_load_env |
| 31 | |
| 32 | # List all configuration objects. |
| 33 | agents_query_agent \ |
| 34 | --node "$NODE_UUID" \ |
| 35 | --host "$AGENT_HOST:19999" \ |
| 36 | --machine-guid "$AGENT_MG" \ |
| 37 | GET '/api/v3/config?action=tree&path=/' |
| 38 | |
| 39 | # Get a specific alert prototype's JSON Schema. |
| 40 | ID='health:alert:prototype:ram_usage' |
| 41 | agents_query_agent \ |
| 42 | --node "$NODE_UUID" \ |
| 43 | --host "$AGENT_HOST:19999" \ |
| 44 | --machine-guid "$AGENT_MG" \ |
| 45 | GET "/api/v3/config?action=schema&id=$(printf %s "$ID" | jq -sRr @uri)" |
| 46 | |
| 47 | # Add a new go.d.plugin nginx job. |
| 48 | TPL='go.d:nginx'; JOB='local_server' |
| 49 | agents_query_agent \ |
| 50 | --node "$NODE_UUID" \ |
| 51 | --host "$AGENT_HOST:19999" \ |
| 52 | --machine-guid "$AGENT_MG" \ |
| 53 | POST "/api/v3/config?action=add&id=$(printf %s "$TPL" | jq -sRr @uri)&name=$JOB" \ |
| 54 | '{"url":"http://127.0.0.1/stub_status","update_every":5}' |
| 55 | ``` |
| 56 | |
| 57 | The wrapper handles the bearer internally; for write actions |
| 58 | (`POST`), Cloud requires `PermissionFunctionExecPrivileged`. Direct- |
| 59 | agent requires the bearer to grant similar access at the agent |
| 60 | level. |
| 61 | |
| 62 | ## When direct-agent is best |
| 63 | |
| 64 | - **Bulk schema fetches.** `tree` -> `schema` for many ids is |
| 65 | faster direct (skip the Cloud round-trip). |
| 66 | - **`update`/`test` write workflows where you want immediate |
| 67 | feedback** without going through Cloud's permission gate. |
| 68 | |
| 69 | ## Limits and gotchas |
| 70 | |
| 71 | - **`/api/v1/config` is the legacy alias** -- use `/api/v3/config`. |
| 72 | - **id encoding**: ids contain colons; URL-encode them with |
| 73 | `printf %s "$ID" | jq -sRr @uri` to avoid breaking on |
| 74 | special characters. |
| 75 | - **`action=test`** without a `name` falls back to a derived name |
| 76 | (the part after the last colon in the id) for backwards |
| 77 | compatibility -- best practice is to supply `name` explicitly. |
| 78 | |
| 79 | ## See also |
| 80 | |
| 81 | - [../query-netdata-cloud/query-dyncfg.md](../query-netdata-cloud/query-dyncfg.md) |
| 82 | -- full reference (actions, id structure, response codes). |
| 83 | - `<repo>/src/daemon/dyncfg/README.md` -- internal DynCfg API. |
| 84 | - `<repo>/src/plugins.d/DYNCFG.md` -- external-plugin DynCfg |
| 85 | protocol. |