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": [
{