sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-08-25 01:01:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update API pages with v0.77.0

Browse Source
This commit is contained in:
netbirddev
2026-08-13 15:30:39 +00:00
parent cdce12501c
commit abb8d4607f
1 changed files with 482 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

528
src/pages/ipa/resources/agent-network.mdx
View File

@@ -1224,7 +1224,7 @@ echo $response;
<Row>
<Col>
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.
</Col>
<Col sticky>
@@ -1380,9 +1380,9 @@ echo $response;
<CodeGroup title="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"
}
```
</CodeGroup>
</Col>
</Row>
---
## Bootstrap Agent Network settings {{ tag: 'POST' , label: '/api/agent-network/settings' }}
<Row>
<Col>
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
<Properties><Property name="proxy_address" type="string" required={false}>
Cluster address to allocate a labeled endpoint beneath. Mutually exclusive with `endpoint`.
</Property>
<Property name="endpoint" type="string" required={false}>
Hostname to claim as the account's self-addressed (dedicated) endpoint. Mutually exclusive with `proxy_address`. Rejected when another account already holds it.
</Property>
<Property name="enable_log_collection" type="boolean" required={false}>
Whether per-request access-log entries are collected for this account's agent-network traffic. Defaults to true.
</Property>
<Property name="enable_prompt_collection" type="boolean" required={false}>
Master switch for request/response prompt capture. Defaults to false.
</Property>
<Property name="redact_pii" type="boolean" required={false}>
Whether captured prompts have PII redacted. Defaults to false.
</Property>
<Property name="access_log_retention_days" type="integer" required={false}>
Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely. Defaults to 30.
</Property>
</Properties>
</Col>
<Col sticky>
<CodeGroup title="Request" tag="POST" label="/api/agent-network/settings">
```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 <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 <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 <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 <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 <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 <TOKEN>")
.build();
Response response = client.newCall(request).execute();
```
```php
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => '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 <TOKEN>'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
```
</CodeGroup>
<CodeGroup title="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;
<Row>
<Col>
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
<Properties><Property name="cluster" type="string" required={false}>
<Properties><Property name="endpoint" type="string" required={true}>
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.
</Property>
<Property name="proxy_address" type="string" required={true}>
Declared cluster address of the proxy serving this account's gateway. Immutable — must match the assigned value; a different value is rejected.
</Property>
<Property name="enable_log_collection" type="boolean" required={true}>
@@ -1441,7 +1737,7 @@ echo $response;
Whether captured prompts have PII redacted.
</Property>
<Property name="access_log_retention_days" type="integer" required={false}>
<Property name="access_log_retention_days" type="integer" required={true}>
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 <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 <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;
<CodeGroup title="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' }}
<Row>
<Col>
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.
</Col>
<Col sticky>
<CodeGroup title="Request" tag="DELETE" label="/api/agent-network/settings">
```bash {{ title: 'cURL' }}
curl -X DELETE https://api.netbird.io/api/agent-network/settings \
-H 'Authorization: Token <TOKEN>'
```
```js
const axios = require('axios');
let config = {
method: 'delete',
maxBodyLength: Infinity,
url: '/api/agent-network/settings',
headers: {
'Authorization': 'Token <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 <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 <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 <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 <TOKEN>")
.build();
Response response = client.newCall(request).execute();
```
```php
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => '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 <TOKEN>'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
```
</CodeGroup>
</Col>
</Row>
---
## List all Agent Network budget rules {{ tag: 'GET' , label: '/api/agent-network/budget-rules' }}
<Row>
@@ -3828,11 +4288,6 @@ echo $response;
Full upstream URL (with scheme) that NetBird forwards traffic to.
</Property>
<Property name="bootstrap_cluster" type="string" required={false}>
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.
</Property>
<Property name="api_key" type="string" required={false}>
@@ -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.
</Property>
<Property name="bootstrap_cluster" type="string" required={false}>
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.
</Property>
<Property name="api_key" type="string" required={false}>
@@ -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": [
{