From abb8d4607fd4a1260c80bcdad1493e92941e1837 Mon Sep 17 00:00:00 2001 From: netbirddev Date: Thu, 13 Aug 2026 15:30:39 +0000 Subject: [PATCH] Update API pages with v0.77.0 --- src/pages/ipa/resources/agent-network.mdx | 528 ++++++++++++++++++++-- 1 file changed, 482 insertions(+), 46 deletions(-) diff --git a/src/pages/ipa/resources/agent-network.mdx b/src/pages/ipa/resources/agent-network.mdx index 35aa43fa..1653e97a 100644 --- a/src/pages/ipa/resources/agent-network.mdx +++ b/src/pages/ipa/resources/agent-network.mdx @@ -1224,7 +1224,7 @@ echo $response; - Returns the per-account Agent Network gateway settings (cluster, subdomain, endpoint). Before the account is bootstrapped — on first provider create (`bootstrap_cluster`) or via PUT with `cluster` — the response carries the default values with empty cluster, subdomain and endpoint. + Returns the per-account Agent Network gateway settings (endpoint, proxy address, collection toggles). Before the account is bootstrapped via POST, the response carries the default values with an empty endpoint and proxy address. @@ -1380,9 +1380,9 @@ echo $response; ```json {{ title: 'Example' }} { - "cluster": "eu.proxy.netbird.io", - "subdomain": "violet", - "endpoint": "violet.eu.proxy.netbird.io", + "endpoint": "brave-otter.eu.proxy.netbird.io", + "proxy_address": "eu.proxy.netbird.io", + "dedicated": false, "enable_log_collection": false, "enable_prompt_collection": false, "redact_pii": false, @@ -1393,9 +1393,300 @@ echo $response; ``` ```json {{ title: 'Schema' }} { - "cluster": "string", - "subdomain": "string", "endpoint": "string", + "proxy_address": "string", + "dedicated": "boolean", + "enable_log_collection": "boolean", + "enable_prompt_collection": "boolean", + "redact_pii": "boolean", + "access_log_retention_days": "integer", + "created_at": "string", + "updated_at": "string" +} +``` + + + + + + +--- + + +## Bootstrap Agent Network settings {{ tag: 'POST' , label: '/api/agent-network/settings' }} + + + + Creates the per-account Agent Network settings row and allocates the account's endpoint. Exactly one of `proxy_address` (labeled endpoint under that cluster; the server allocates the label) and `endpoint` (self-addressed dedicated endpoint, claimed verbatim) must be provided. The endpoint and proxy address are immutable once assigned. Returns 409 when the account already has a settings row. + + ### Request-Body Parameters + + + + Cluster address to allocate a labeled endpoint beneath. Mutually exclusive with `endpoint`. + + + + + Hostname to claim as the account's self-addressed (dedicated) endpoint. Mutually exclusive with `proxy_address`. Rejected when another account already holds it. + + + + + Whether per-request access-log entries are collected for this account's agent-network traffic. Defaults to true. + + + + + Master switch for request/response prompt capture. Defaults to false. + + + + + Whether captured prompts have PII redacted. Defaults to false. + + + + + Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely. Defaults to 30. + + + + + + + + + +```bash {{ title: 'cURL' }} +curl -X POST https://api.netbird.io/api/agent-network/settings \ +-H 'Accept: application/json' \ +-H 'Content-Type: application/json' \ +-H 'Authorization: Token ' \ +--data-raw '{ + "proxy_address": "eu.proxy.netbird.io", + "endpoint": "brave-otter.gateway.example.com", + "enable_log_collection": true, + "enable_prompt_collection": false, + "redact_pii": false, + "access_log_retention_days": 30 +}' +``` + +```js +const axios = require('axios'); +let data = JSON.stringify({ + "proxy_address": "eu.proxy.netbird.io", + "endpoint": "brave-otter.gateway.example.com", + "enable_log_collection": true, + "enable_prompt_collection": false, + "redact_pii": false, + "access_log_retention_days": 30 +}); +let config = { + method: 'post', + maxBodyLength: Infinity, + url: '/api/agent-network/settings', + headers: { + 'Accept': 'application/json', + 'Content-Type': 'application/json', + 'Authorization': 'Token ' + }, + data : data +}; + +axios(config) +.then((response) => { + console.log(JSON.stringify(response.data)); +}) +.catch((error) => { + console.log(error); +}); +``` + +```python +import requests +import json + +url = "https://api.netbird.io/api/agent-network/settings" +payload = json.dumps({ + "proxy_address": "eu.proxy.netbird.io", + "endpoint": "brave-otter.gateway.example.com", + "enable_log_collection": true, + "enable_prompt_collection": false, + "redact_pii": false, + "access_log_retention_days": 30 +}) +headers = { + 'Content-Type': 'application/json', + 'Accept': 'application/json', + 'Authorization': 'Token ' +} + +response = requests.request("POST", url, headers=headers, data=payload) + +print(response.text) +``` + +```go +package main + +import ( + "fmt" + "strings" + "net/http" + "io/ioutil" +) + +func main() { + + url := "https://api.netbird.io/api/agent-network/settings" + method := "POST" + + payload := strings.NewReader(`{ + "proxy_address": "eu.proxy.netbird.io", + "endpoint": "brave-otter.gateway.example.com", + "enable_log_collection": true, + "enable_prompt_collection": false, + "redact_pii": false, + "access_log_retention_days": 30 +}`) + client := &http.Client { + } + req, err := http.NewRequest(method, url, payload) + + if err != nil { + fmt.Println(err) + return + } + + + req.Header.Add("Content-Type", "application/json") + req.Header.Add("Accept", "application/json") + req.Header.Add("Authorization", "Token ") + + res, err := client.Do(req) + if err != nil { + fmt.Println(err) + return + } + defer res.Body.Close() + + body, err := ioutil.ReadAll(res.Body) + if err != nil { + fmt.Println(err) + return + } + fmt.Println(string(body)) +} +``` + +```ruby +require "uri" +require "json" +require "net/http" + +url = URI("https://api.netbird.io/api/agent-network/settings") + +https = Net::HTTP.new(url.host, url.port) +https.use_ssl = true + +request = Net::HTTP::Post.new(url) +request["Content-Type"] = "application/json" +request["Accept"] = "application/json" +request["Authorization"] = "Token " + +request.body = JSON.dump({ + "proxy_address": "eu.proxy.netbird.io", + "endpoint": "brave-otter.gateway.example.com", + "enable_log_collection": true, + "enable_prompt_collection": false, + "redact_pii": false, + "access_log_retention_days": 30 +}) +response = https.request(request) +puts response.read_body +``` + +```java +OkHttpClient client = new OkHttpClient().newBuilder() + .build(); +MediaType mediaType = MediaType.parse("application/json"); +RequestBody body = RequestBody.create(mediaType, '{ + "proxy_address": "eu.proxy.netbird.io", + "endpoint": "brave-otter.gateway.example.com", + "enable_log_collection": true, + "enable_prompt_collection": false, + "redact_pii": false, + "access_log_retention_days": 30 +}'); +Request request = new Request.Builder() + .url("https://api.netbird.io/api/agent-network/settings") + .method("POST", body) + .addHeader("Content-Type", "application/json") + .addHeader("Accept", "application/json") + .addHeader("Authorization: Token ") + .build(); +Response response = client.newCall(request).execute(); +``` + +```php + 'https://api.netbird.io/api/agent-network/settings', + CURLOPT_RETURNTRANSFER => true, + CURLOPT_ENCODING => '', + CURLOPT_MAXREDIRS => 10, + CURLOPT_TIMEOUT => 0, + CURLOPT_FOLLOWLOCATION => true, + CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, + CURLOPT_CUSTOMREQUEST => 'POST', + CURLOPT_POSTFIELDS => '{ + "proxy_address": "eu.proxy.netbird.io", + "endpoint": "brave-otter.gateway.example.com", + "enable_log_collection": true, + "enable_prompt_collection": false, + "redact_pii": false, + "access_log_retention_days": 30 +}', + CURLOPT_HTTPHEADER => array( + 'Content-Type: application/json', + 'Accept: application/json', + 'Authorization: Token ' + ), +)); + +$response = curl_exec($curl); + +curl_close($curl); +echo $response; +``` + + + + + +```json {{ title: 'Example' }} +{ + "endpoint": "brave-otter.eu.proxy.netbird.io", + "proxy_address": "eu.proxy.netbird.io", + "dedicated": false, + "enable_log_collection": false, + "enable_prompt_collection": false, + "redact_pii": false, + "access_log_retention_days": 30, + "created_at": "2026-04-26T10:30:00Z", + "updated_at": "2026-04-26T10:30:00Z" +} +``` +```json {{ title: 'Schema' }} +{ + "endpoint": "string", + "proxy_address": "string", + "dedicated": "boolean", "enable_log_collection": "boolean", "enable_prompt_collection": "boolean", "redact_pii": "boolean", @@ -1417,13 +1708,18 @@ echo $response; - Updates the account-level Agent Network settings; the request replaces every mutable field (collection toggles and retention). When the account has no settings row yet, providing `cluster` bootstraps it (assigning the subdomain that forms the agent endpoint); without `cluster` the request returns 404. Sending a `cluster` different from the assigned one is rejected (the cluster is immutable once assigned). The subdomain is always server-assigned and immutable. + Updates the account-level Agent Network settings; the request carries every field, replacing the mutable ones (collection toggles and retention). Returns 404 when the account has no settings row yet — bootstrap it with POST first. The endpoint and proxy address are assigned at bootstrap and immutable; the request must carry them unchanged, and a request carrying different values is rejected. ### Request-Body Parameters - + - Address of the NetBird proxy cluster fronting this account's agent-network endpoint. When the account has no settings row yet, providing it bootstraps the row (assigning the subdomain that forms the agent endpoint). The cluster is immutable once assigned — later updates must omit it or send the assigned value; any other value is rejected. + The account's gateway endpoint hostname. Immutable — must match the assigned value; a different value is rejected. + + + + + Declared cluster address of the proxy serving this account's gateway. Immutable — must match the assigned value; a different value is rejected. @@ -1441,7 +1737,7 @@ echo $response; Whether captured prompts have PII redacted. - + Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely. @@ -1459,7 +1755,8 @@ curl -X PUT https://api.netbird.io/api/agent-network/settings \ -H 'Content-Type: application/json' \ -H 'Authorization: Token ' \ --data-raw '{ - "cluster": "eu.proxy.netbird.io", + "endpoint": "brave-otter.eu.proxy.netbird.io", + "proxy_address": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": true, "redact_pii": true, @@ -1470,7 +1767,8 @@ curl -X PUT https://api.netbird.io/api/agent-network/settings \ ```js const axios = require('axios'); let data = JSON.stringify({ - "cluster": "eu.proxy.netbird.io", + "endpoint": "brave-otter.eu.proxy.netbird.io", + "proxy_address": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": true, "redact_pii": true, @@ -1503,7 +1801,8 @@ import json url = "https://api.netbird.io/api/agent-network/settings" payload = json.dumps({ - "cluster": "eu.proxy.netbird.io", + "endpoint": "brave-otter.eu.proxy.netbird.io", + "proxy_address": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": true, "redact_pii": true, @@ -1536,7 +1835,8 @@ func main() { method := "PUT" payload := strings.NewReader(`{ - "cluster": "eu.proxy.netbird.io", + "endpoint": "brave-otter.eu.proxy.netbird.io", + "proxy_address": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": true, "redact_pii": true, @@ -1588,7 +1888,8 @@ request["Accept"] = "application/json" request["Authorization"] = "Token " request.body = JSON.dump({ - "cluster": "eu.proxy.netbird.io", + "endpoint": "brave-otter.eu.proxy.netbird.io", + "proxy_address": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": true, "redact_pii": true, @@ -1603,7 +1904,8 @@ OkHttpClient client = new OkHttpClient().newBuilder() .build(); MediaType mediaType = MediaType.parse("application/json"); RequestBody body = RequestBody.create(mediaType, '{ - "cluster": "eu.proxy.netbird.io", + "endpoint": "brave-otter.eu.proxy.netbird.io", + "proxy_address": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": true, "redact_pii": true, @@ -1634,7 +1936,8 @@ curl_setopt_array($curl, array( CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'PUT', CURLOPT_POSTFIELDS => '{ - "cluster": "eu.proxy.netbird.io", + "endpoint": "brave-otter.eu.proxy.netbird.io", + "proxy_address": "eu.proxy.netbird.io", "enable_log_collection": true, "enable_prompt_collection": true, "redact_pii": true, @@ -1659,9 +1962,9 @@ echo $response; ```json {{ title: 'Example' }} { - "cluster": "eu.proxy.netbird.io", - "subdomain": "violet", - "endpoint": "violet.eu.proxy.netbird.io", + "endpoint": "brave-otter.eu.proxy.netbird.io", + "proxy_address": "eu.proxy.netbird.io", + "dedicated": false, "enable_log_collection": false, "enable_prompt_collection": false, "redact_pii": false, @@ -1672,9 +1975,9 @@ echo $response; ``` ```json {{ title: 'Schema' }} { - "cluster": "string", - "subdomain": "string", "endpoint": "string", + "proxy_address": "string", + "dedicated": "boolean", "enable_log_collection": "boolean", "enable_prompt_collection": "boolean", "redact_pii": "boolean", @@ -1692,6 +1995,163 @@ echo $response; --- +## Delete Agent Network settings {{ tag: 'DELETE' , label: '/api/agent-network/settings' }} + + + + Deletes the account's Agent Network settings row, releasing the endpoint. Guarded — the delete is refused with 412 while any Agent Network provider exists for the account or while a proxy is actively serving the endpoint. Bootstrapping again after a delete allocates a new endpoint; the released hostname is not reserved. + + + + +```bash {{ title: 'cURL' }} +curl -X DELETE https://api.netbird.io/api/agent-network/settings \ +-H 'Authorization: Token ' +``` + +```js +const axios = require('axios'); + +let config = { + method: 'delete', + maxBodyLength: Infinity, + url: '/api/agent-network/settings', + headers: { + 'Authorization': 'Token ' + } +}; + +axios(config) +.then((response) => { + console.log(JSON.stringify(response.data)); +}) +.catch((error) => { + console.log(error); +}); +``` + +```python +import requests +import json + +url = "https://api.netbird.io/api/agent-network/settings" + +headers = { + 'Authorization': 'Token ' +} + +response = requests.request("DELETE", url, headers=headers) + +print(response.text) +``` + +```go +package main + +import ( + "fmt" + "strings" + "net/http" + "io/ioutil" +) + +func main() { + + url := "https://api.netbird.io/api/agent-network/settings" + method := "DELETE" + + client := &http.Client { + } + req, err := http.NewRequest(method, url, nil) + + if err != nil { + fmt.Println(err) + return + } + + + req.Header.Add("Authorization", "Token ") + + res, err := client.Do(req) + if err != nil { + fmt.Println(err) + return + } + defer res.Body.Close() + + body, err := ioutil.ReadAll(res.Body) + if err != nil { + fmt.Println(err) + return + } + fmt.Println(string(body)) +} +``` + +```ruby +require "uri" +require "json" +require "net/http" + +url = URI("https://api.netbird.io/api/agent-network/settings") + +https = Net::HTTP.new(url.host, url.port) +https.use_ssl = true + +request = Net::HTTP::Delete.new(url) +request["Authorization"] = "Token " + +response = https.request(request) +puts response.read_body +``` + +```java +OkHttpClient client = new OkHttpClient().newBuilder() + .build(); + +Request request = new Request.Builder() + .url("https://api.netbird.io/api/agent-network/settings") + .method("DELETE") + .addHeader("Authorization: Token ") + .build(); +Response response = client.newCall(request).execute(); +``` + +```php + 'https://api.netbird.io/api/agent-network/settings', + CURLOPT_RETURNTRANSFER => true, + CURLOPT_ENCODING => '', + CURLOPT_MAXREDIRS => 10, + CURLOPT_TIMEOUT => 0, + CURLOPT_FOLLOWLOCATION => true, + CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, + CURLOPT_CUSTOMREQUEST => 'DELETE', + CURLOPT_HTTPHEADER => array( + 'Authorization: Token ' + ), +)); + +$response = curl_exec($curl); + +curl_close($curl); +echo $response; +``` + + + + + + + + +--- + + ## List all Agent Network budget rules {{ tag: 'GET' , label: '/api/agent-network/budget-rules' }} @@ -3828,11 +4288,6 @@ echo $response; Full upstream URL (with scheme) that NetBird forwards traffic to. - - - - Proxy cluster used to bootstrap the per-account agent-network endpoint when the first provider is created. Ignored on subsequent creates and on updates because the cluster is pinned on the account-level Settings row. - @@ -3930,7 +4385,6 @@ curl -X POST https://api.netbird.io/api/agent-network/providers \ "provider_id": "openai_api", "name": "OpenAI API", "upstream_url": "https://api.openai.com", - "bootstrap_cluster": "eu.proxy.netbird.io", "api_key": "sk-...", "models": [ { @@ -3959,7 +4413,6 @@ let data = JSON.stringify({ "provider_id": "openai_api", "name": "OpenAI API", "upstream_url": "https://api.openai.com", - "bootstrap_cluster": "eu.proxy.netbird.io", "api_key": "sk-...", "models": [ { @@ -4010,7 +4463,6 @@ payload = json.dumps({ "provider_id": "openai_api", "name": "OpenAI API", "upstream_url": "https://api.openai.com", - "bootstrap_cluster": "eu.proxy.netbird.io", "api_key": "sk-...", "models": [ { @@ -4061,7 +4513,6 @@ func main() { "provider_id": "openai_api", "name": "OpenAI API", "upstream_url": "https://api.openai.com", - "bootstrap_cluster": "eu.proxy.netbird.io", "api_key": "sk-...", "models": [ { @@ -4131,7 +4582,6 @@ request.body = JSON.dump({ "provider_id": "openai_api", "name": "OpenAI API", "upstream_url": "https://api.openai.com", - "bootstrap_cluster": "eu.proxy.netbird.io", "api_key": "sk-...", "models": [ { @@ -4164,7 +4614,6 @@ RequestBody body = RequestBody.create(mediaType, '{ "provider_id": "openai_api", "name": "OpenAI API", "upstream_url": "https://api.openai.com", - "bootstrap_cluster": "eu.proxy.netbird.io", "api_key": "sk-...", "models": [ { @@ -4213,7 +4662,6 @@ curl_setopt_array($curl, array( "provider_id": "openai_api", "name": "OpenAI API", "upstream_url": "https://api.openai.com", - "bootstrap_cluster": "eu.proxy.netbird.io", "api_key": "sk-...", "models": [ { @@ -4587,11 +5035,6 @@ echo $response; Full upstream URL (with scheme) that NetBird forwards traffic to. - - - - Proxy cluster used to bootstrap the per-account agent-network endpoint when the first provider is created. Ignored on subsequent creates and on updates because the cluster is pinned on the account-level Settings row. - @@ -4689,7 +5132,6 @@ curl -X PUT https://api.netbird.io/api/agent-network/providers/{providerId} \ "provider_id": "openai_api", "name": "OpenAI API", "upstream_url": "https://api.openai.com", - "bootstrap_cluster": "eu.proxy.netbird.io", "api_key": "sk-...", "models": [ { @@ -4718,7 +5160,6 @@ let data = JSON.stringify({ "provider_id": "openai_api", "name": "OpenAI API", "upstream_url": "https://api.openai.com", - "bootstrap_cluster": "eu.proxy.netbird.io", "api_key": "sk-...", "models": [ { @@ -4769,7 +5210,6 @@ payload = json.dumps({ "provider_id": "openai_api", "name": "OpenAI API", "upstream_url": "https://api.openai.com", - "bootstrap_cluster": "eu.proxy.netbird.io", "api_key": "sk-...", "models": [ { @@ -4820,7 +5260,6 @@ func main() { "provider_id": "openai_api", "name": "OpenAI API", "upstream_url": "https://api.openai.com", - "bootstrap_cluster": "eu.proxy.netbird.io", "api_key": "sk-...", "models": [ { @@ -4890,7 +5329,6 @@ request.body = JSON.dump({ "provider_id": "openai_api", "name": "OpenAI API", "upstream_url": "https://api.openai.com", - "bootstrap_cluster": "eu.proxy.netbird.io", "api_key": "sk-...", "models": [ { @@ -4923,7 +5361,6 @@ RequestBody body = RequestBody.create(mediaType, '{ "provider_id": "openai_api", "name": "OpenAI API", "upstream_url": "https://api.openai.com", - "bootstrap_cluster": "eu.proxy.netbird.io", "api_key": "sk-...", "models": [ { @@ -4972,7 +5409,6 @@ curl_setopt_array($curl, array( "provider_id": "openai_api", "name": "OpenAI API", "upstream_url": "https://api.openai.com", - "bootstrap_cluster": "eu.proxy.netbird.io", "api_key": "sk-...", "models": [ {