some file
GET/api/agent-network/access-logs

List Agent Network access logs

Returns a paginated, server-side-filtered list of agent-network (LLM) access log entries. Available only when the account has log collection enabled; otherwise entries are not retained.

Query Parameters

  • Name
    page
    Type
    integer
    Required
    optional
    Enum
    Description

    Page number for pagination (1-indexed).

  • Name
    page_size
    Type
    integer
    Required
    optional
    Enum
    Description

    Number of items per page (max 100).

  • Name
    sort_by
    Type
    string
    Required
    optional
    Enum
    Description

    Field to sort by.

  • Name
    sort_order
    Type
    string
    Required
    optional
    Enum
    Description

    Sort order (ascending or descending).

  • Name
    search
    Type
    string
    Required
    optional
    Enum
    Description

    General search across log ID, host, path, model, and user email/name.

  • Name
    user_id
    Type
    string
    Required
    optional
    Enum
    Description

    Filter by authenticated user ID.

  • Name
    session_id
    Type
    string
    Required
    optional
    Enum
    Description

    Filter to a single conversation / coding session id (groups all requests of one session).

  • Name
    group_id
    Type
    array
    Required
    optional
    Enum
    Description

    Filter by authorising group id. Repeat for multiple (matches any).

  • Name
    provider_id
    Type
    array
    Required
    optional
    Enum
    Description

    Filter by resolved provider id. Repeat for multiple (matches any).

  • Name
    model
    Type
    array
    Required
    optional
    Enum
    Description

    Filter by model. Repeat for multiple (matches any).

  • Name
    decision
    Type
    string
    Required
    optional
    Enum
    Description

    Filter by policy decision (e.g. allow, deny).

  • Name
    path
    Type
    string
    Required
    optional
    Enum
    Description

    Filter by request path prefix (matches entries whose path starts with this value).

  • Name
    start_date
    Type
    string
    Required
    optional
    Enum
    Description

    Filter by timestamp >= start_date (RFC3339 format).

  • Name
    end_date
    Type
    string
    Required
    optional
    Enum
    Description

    Filter by timestamp <= end_date (RFC3339 format).

Request

GET
/api/agent-network/access-logs
curl -X GET https://api.netbird.io/api/agent-network/access-logs \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

{
  "data": [
    {
      "id": "ch8i4ug6lnn4g9hqv7m0",
      "service_id": {
        "type": "string",
        "description": "ID of the synthesised agent-network service that handled the request."
      },
      "timestamp": "2026-05-05T12:34:56Z",
      "status_code": 200,
      "duration_ms": 850,
      "user_id": {
        "type": "string",
        "description": "NetBird user id of the authenticated caller, if applicable."
      },
      "source_ip": {
        "type": "string",
        "description": "Source IP of the request. Empty when log collection is disabled."
      },
      "method": "POST",
      "host": {
        "type": "string",
        "description": "Upstream host the request was routed to. Empty when log collection is disabled."
      },
      "path": {
        "type": "string",
        "description": "Request path. Empty when log collection is disabled."
      },
      "provider": "openai",
      "model": "gpt-4o",
      "session_id": "019eeb72-ab7c-7cd2-aa05-6e8eb834afcb",
      "resolved_provider_id": {
        "type": "string",
        "description": "NetBird agent-network provider id that served the request."
      },
      "selected_policy_id": {
        "type": "string",
        "description": "Agent-network policy id that authorised (or denied) the request."
      },
      "decision": "allow",
      "deny_reason": {
        "type": "string",
        "description": "Raw deny reason code when the request was blocked (e.g. llm_policy.token_cap_exceeded)."
      },
      "input_tokens": 1200,
      "output_tokens": 640,
      "total_tokens": 1840,
      "cost_usd": 0.0231,
      "stream": {
        "type": "boolean",
        "description": "Whether the request was a streaming completion."
      },
      "group_ids": [
        {
          "type": "string"
        }
      ],
      "request_prompt": {
        "type": "string",
        "description": "Captured request prompt. Present only when prompt collection is enabled."
      },
      "response_completion": {
        "type": "string",
        "description": "Captured response completion. Present only when prompt collection is enabled."
      }
    }
  ],
  "page": 1,
  "page_size": 50,
  "total_records": 523,
  "total_pages": 11
}
GET/api/agent-network/usage/overview

Agent Network usage overview

Returns agent-network token and cost usage aggregated into time buckets, server-side filtered. Usage is always collected (independent of log collection).

Query Parameters

  • Name
    granularity
    Type
    string
    Required
    optional
    Enum
    Description

    Time bucket width. Defaults to day.

  • Name
    start_date
    Type
    string
    Required
    optional
    Enum
    Description

    Filter by timestamp >= start_date (RFC3339 format).

  • Name
    end_date
    Type
    string
    Required
    optional
    Enum
    Description

    Filter by timestamp <= end_date (RFC3339 format).

  • Name
    user_id
    Type
    string
    Required
    optional
    Enum
    Description

    Filter by user ID.

  • Name
    session_id
    Type
    string
    Required
    optional
    Enum
    Description

    Filter to a single conversation / coding session id.

  • Name
    group_id
    Type
    array
    Required
    optional
    Enum
    Description

    Filter by authorising group id. Repeat for multiple (matches any).

  • Name
    provider_id
    Type
    array
    Required
    optional
    Enum
    Description

    Filter by resolved provider id. Repeat for multiple (matches any).

  • Name
    model
    Type
    array
    Required
    optional
    Enum
    Description

    Filter by model. Repeat for multiple (matches any).

Request

GET
/api/agent-network/usage/overview
curl -X GET https://api.netbird.io/api/agent-network/usage/overview \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

[
  {
    "period_start": "2026-05-05",
    "input_tokens": 120000,
    "output_tokens": 64000,
    "total_tokens": 184000,
    "cost_usd": 2.31
  }
]
GET/api/agent-network/consumption

List Agent Network consumption counters

Returns every per-(dimension, window) consumption counter recorded for the account, ordered window-newest-first. Empty list when nothing has been consumed yet.

Request

GET
/api/agent-network/consumption
curl -X GET https://api.netbird.io/api/agent-network/consumption \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

[
  {
    "dimension_kind": {
      "type": "string",
      "enum": [
        "user",
        "group"
      ],
      "description": "Whether this row counts a single end user or a single source group across every member."
    },
    "dimension_id": "grp-engineers",
    "window_seconds": 86400,
    "window_start_utc": "2026-05-05T12:00:00Z",
    "tokens_input": 12000,
    "tokens_output": 6500,
    "cost_usd": 0.4231,
    "updated_at": "2026-05-05T12:34:56Z"
  }
]
GET/api/agent-network/settings

Retrieve Agent Network settings

Returns the per-account Agent Network gateway settings (cluster, subdomain, endpoint). Returns 404 when no provider has been created yet — settings are lazily bootstrapped on first provider create.

Request

GET
/api/agent-network/settings
curl -X GET https://api.netbird.io/api/agent-network/settings \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

{
  "cluster": "eu.proxy.netbird.io",
  "subdomain": "violet",
  "endpoint": "violet.eu.proxy.netbird.io",
  "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"
}
PUT/api/agent-network/settings

Update Agent Network settings

Updates the mutable account-level Agent Network settings (collection toggles). Cluster and subdomain are immutable and ignored if sent. Returns 404 when settings have not been bootstrapped (no provider created yet).

Request-Body Parameters

  • Name
    enable_log_collection
    Type
    boolean
    Required
    required
    Enum
    Description

    Whether per-request access-log entries are collected for this account's agent-network traffic.

  • Name
    enable_prompt_collection
    Type
    boolean
    Required
    required
    Enum
    Description

    Master switch for request/response prompt capture.

  • Name
    redact_pii
    Type
    boolean
    Required
    required
    Enum
    Description

    Whether captured prompts have PII redacted.

  • Name
    access_log_retention_days
    Type
    integer
    Required
    optional
    Enum
    Description

    Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely.

Request

PUT
/api/agent-network/settings
curl -X PUT https://api.netbird.io/api/agent-network/settings \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Token <TOKEN>' \
--data-raw '{
  "enable_log_collection": true,
  "enable_prompt_collection": true,
  "redact_pii": true,
  "access_log_retention_days": 30
}'

Response

{
  "cluster": "eu.proxy.netbird.io",
  "subdomain": "violet",
  "endpoint": "violet.eu.proxy.netbird.io",
  "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"
}
GET/api/agent-network/budget-rules

List all Agent Network budget rules

Returns all account-level budget rules.

Request

GET
/api/agent-network/budget-rules
curl -X GET https://api.netbird.io/api/agent-network/budget-rules \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

[
  {
    "id": "ainbud_d1m3kebd9pcs0c1pnu7g",
    "name": "Org monthly ceiling",
    "enabled": true,
    "target_groups": [
      "ch8vp3o6lnna9hg0sd8g"
    ],
    "target_users": [],
    "limits": {
      "token_limit": {
        "enabled": true,
        "group_cap": 10000000,
        "user_cap": 1000000,
        "window_seconds": 2592000
      },
      "budget_limit": {
        "enabled": true,
        "group_cap_usd": 1000,
        "user_cap_usd": 100,
        "window_seconds": 2592000
      }
    },
    "created_at": "2026-04-26T10:30:00Z",
    "updated_at": "2026-04-26T10:30:00Z"
  }
]
POST/api/agent-network/budget-rules

Create an Agent Network budget rule

Creates a new account-level budget rule.

Request-Body Parameters

  • Name
    name
    Type
    string
    Required
    required
    Enum
    Description

    Display name for the budget rule.

  • Name
    enabled
    Type
    boolean
    Required
    optional
    Enum
    Description

    Whether the rule is enforced. Defaults to true on create.

  • Name
    target_groups
    Type
    string[]
    Required
    optional
    Enum
    Description

    NetBird group ids the rule binds. Empty plus empty target_users means account-wide.

  • Name
    target_users
    Type
    string[]
    Required
    optional
    Enum
    Description

    NetBird user ids the rule binds directly.

  • Name
    limits
    Type
    object
    Required
    required
    Enum
    Description
    Token and budget caps attached directly to the policy. These compose with any guardrail-level checks.
      • Name
        token_limit
        Type
        object
        Required
        required
        Enum
        Description
        Per-policy token cap. group_cap is applied to each source group independently — every group in the policy's source_groups gets its own bucket of this size. user_cap is applied independently to each individual user. Caps reset to zero at the start of each window.
          • Name
            enabled
            Type
            boolean
            Required
            required
            Enum
            Description
          • Name
            group_cap
            Type
            integer
            Required
            required
            Enum
            00
            Description

            Tokens allowed per source group within the window (each group has its own bucket of this size). 0 means uncapped.

          • Name
            user_cap
            Type
            integer
            Required
            required
            Enum
            00
            Description

            Tokens allowed per individual user within the window. 0 means uncapped.

          • Name
            window_seconds
            Type
            integer
            Required
            required
            Enum
            Possible Values: >=60
            Description

            Reset frequency in seconds. The cap counter resets to zero at the start of each window. Minimum 60 (one minute) when the limit is enabled.

      • Name
        budget_limit
        Type
        object
        Required
        required
        Enum
        Description
        Per-policy USD spend cap. group_cap_usd is applied to each source group independently — every group in the policy's source_groups gets its own bucket of this size. user_cap_usd is applied independently to each individual user. Caps reset to zero at the start of each window.
          • Name
            enabled
            Type
            boolean
            Required
            required
            Enum
            Description
          • Name
            group_cap_usd
            Type
            number
            Required
            required
            Enum
            00
            Description

            USD allowed per source group within the window (each group has its own bucket of this size). 0 means uncapped.

          • Name
            user_cap_usd
            Type
            number
            Required
            required
            Enum
            00
            Description

            USD allowed per individual user within the window. 0 means uncapped.

          • Name
            window_seconds
            Type
            integer
            Required
            required
            Enum
            Possible Values: >=60
            Description

            Reset frequency in seconds. Caps reset at the start of each window. Minimum 60 (one minute) when the limit is enabled.

Request

POST
/api/agent-network/budget-rules
curl -X POST https://api.netbird.io/api/agent-network/budget-rules \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Token <TOKEN>' \
--data-raw '{
  "name": "Org monthly ceiling",
  "enabled": true,
  "target_groups": [
    "ch8vp3o6lnna9hg0sd8g"
  ],
  "target_users": [],
  "limits": {
    "token_limit": {
      "enabled": true,
      "group_cap": 10000000,
      "user_cap": 1000000,
      "window_seconds": 2592000
    },
    "budget_limit": {
      "enabled": true,
      "group_cap_usd": 1000,
      "user_cap_usd": 100,
      "window_seconds": 2592000
    }
  }
}'

Response

{
  "id": "ainbud_d1m3kebd9pcs0c1pnu7g",
  "name": "Org monthly ceiling",
  "enabled": true,
  "target_groups": [
    "ch8vp3o6lnna9hg0sd8g"
  ],
  "target_users": [],
  "limits": {
    "token_limit": {
      "enabled": true,
      "group_cap": 10000000,
      "user_cap": 1000000,
      "window_seconds": 2592000
    },
    "budget_limit": {
      "enabled": true,
      "group_cap_usd": 1000,
      "user_cap_usd": 100,
      "window_seconds": 2592000
    }
  },
  "created_at": "2026-04-26T10:30:00Z",
  "updated_at": "2026-04-26T10:30:00Z"
}
GET/api/agent-network/budget-rules/{ruleId}

Retrieve an Agent Network budget rule

Get a specific account-level budget rule.

Path Parameters

  • Name
    ruleId
    Type
    string
    Required
    required
    Enum
    Description

    The unique identifier of a budget rule

Request

GET
/api/agent-network/budget-rules/{ruleId}
curl -X GET https://api.netbird.io/api/agent-network/budget-rules/{ruleId} \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

{
  "id": "ainbud_d1m3kebd9pcs0c1pnu7g",
  "name": "Org monthly ceiling",
  "enabled": true,
  "target_groups": [
    "ch8vp3o6lnna9hg0sd8g"
  ],
  "target_users": [],
  "limits": {
    "token_limit": {
      "enabled": true,
      "group_cap": 10000000,
      "user_cap": 1000000,
      "window_seconds": 2592000
    },
    "budget_limit": {
      "enabled": true,
      "group_cap_usd": 1000,
      "user_cap_usd": 100,
      "window_seconds": 2592000
    }
  },
  "created_at": "2026-04-26T10:30:00Z",
  "updated_at": "2026-04-26T10:30:00Z"
}
PUT/api/agent-network/budget-rules/{ruleId}

Update an Agent Network budget rule

Updates an existing account-level budget rule.

Path Parameters

  • Name
    ruleId
    Type
    string
    Required
    required
    Enum
    Description

    The unique identifier of a budget rule

Request-Body Parameters

  • Name
    name
    Type
    string
    Required
    required
    Enum
    Description

    Display name for the budget rule.

  • Name
    enabled
    Type
    boolean
    Required
    optional
    Enum
    Description

    Whether the rule is enforced. Defaults to true on create.

  • Name
    target_groups
    Type
    string[]
    Required
    optional
    Enum
    Description

    NetBird group ids the rule binds. Empty plus empty target_users means account-wide.

  • Name
    target_users
    Type
    string[]
    Required
    optional
    Enum
    Description

    NetBird user ids the rule binds directly.

  • Name
    limits
    Type
    object
    Required
    required
    Enum
    Description
    Token and budget caps attached directly to the policy. These compose with any guardrail-level checks.
      • Name
        token_limit
        Type
        object
        Required
        required
        Enum
        Description
        Per-policy token cap. group_cap is applied to each source group independently — every group in the policy's source_groups gets its own bucket of this size. user_cap is applied independently to each individual user. Caps reset to zero at the start of each window.
          • Name
            enabled
            Type
            boolean
            Required
            required
            Enum
            Description
          • Name
            group_cap
            Type
            integer
            Required
            required
            Enum
            00
            Description

            Tokens allowed per source group within the window (each group has its own bucket of this size). 0 means uncapped.

          • Name
            user_cap
            Type
            integer
            Required
            required
            Enum
            00
            Description

            Tokens allowed per individual user within the window. 0 means uncapped.

          • Name
            window_seconds
            Type
            integer
            Required
            required
            Enum
            Possible Values: >=60
            Description

            Reset frequency in seconds. The cap counter resets to zero at the start of each window. Minimum 60 (one minute) when the limit is enabled.

      • Name
        budget_limit
        Type
        object
        Required
        required
        Enum
        Description
        Per-policy USD spend cap. group_cap_usd is applied to each source group independently — every group in the policy's source_groups gets its own bucket of this size. user_cap_usd is applied independently to each individual user. Caps reset to zero at the start of each window.
          • Name
            enabled
            Type
            boolean
            Required
            required
            Enum
            Description
          • Name
            group_cap_usd
            Type
            number
            Required
            required
            Enum
            00
            Description

            USD allowed per source group within the window (each group has its own bucket of this size). 0 means uncapped.

          • Name
            user_cap_usd
            Type
            number
            Required
            required
            Enum
            00
            Description

            USD allowed per individual user within the window. 0 means uncapped.

          • Name
            window_seconds
            Type
            integer
            Required
            required
            Enum
            Possible Values: >=60
            Description

            Reset frequency in seconds. Caps reset at the start of each window. Minimum 60 (one minute) when the limit is enabled.

Request

PUT
/api/agent-network/budget-rules/{ruleId}
curl -X PUT https://api.netbird.io/api/agent-network/budget-rules/{ruleId} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Token <TOKEN>' \
--data-raw '{
  "name": "Org monthly ceiling",
  "enabled": true,
  "target_groups": [
    "ch8vp3o6lnna9hg0sd8g"
  ],
  "target_users": [],
  "limits": {
    "token_limit": {
      "enabled": true,
      "group_cap": 10000000,
      "user_cap": 1000000,
      "window_seconds": 2592000
    },
    "budget_limit": {
      "enabled": true,
      "group_cap_usd": 1000,
      "user_cap_usd": 100,
      "window_seconds": 2592000
    }
  }
}'

Response

{
  "id": "ainbud_d1m3kebd9pcs0c1pnu7g",
  "name": "Org monthly ceiling",
  "enabled": true,
  "target_groups": [
    "ch8vp3o6lnna9hg0sd8g"
  ],
  "target_users": [],
  "limits": {
    "token_limit": {
      "enabled": true,
      "group_cap": 10000000,
      "user_cap": 1000000,
      "window_seconds": 2592000
    },
    "budget_limit": {
      "enabled": true,
      "group_cap_usd": 1000,
      "user_cap_usd": 100,
      "window_seconds": 2592000
    }
  },
  "created_at": "2026-04-26T10:30:00Z",
  "updated_at": "2026-04-26T10:30:00Z"
}
DELETE/api/agent-network/budget-rules/{ruleId}

Delete an Agent Network budget rule

Deletes an account-level budget rule.

Path Parameters

  • Name
    ruleId
    Type
    string
    Required
    required
    Enum
    Description

    The unique identifier of a budget rule

Request

DELETE
/api/agent-network/budget-rules/{ruleId}
curl -X DELETE https://api.netbird.io/api/agent-network/budget-rules/{ruleId} \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

{
  "type": "object"
}
GET/api/agent-network/catalog/providers

List Agent Network catalog providers

Returns the static catalog of supported Agent Network providers (OpenAI, Anthropic, …) along with their default upstream host, auth header template, brand color, and known models.

Request

GET
/api/agent-network/catalog/providers
curl -X GET https://api.netbird.io/api/agent-network/catalog/providers \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

[
  {
    "id": "openai_api",
    "name": "OpenAI API",
    "description": "GPT, Responses API, and Embeddings",
    "default_host": "api.openai.com",
    "auth_header_template": "Bearer ${API_KEY}",
    "default_content_type": "application/json",
    "brand_color": "#10A37F",
    "kind": "provider",
    "extra_headers": [
      {
        "name": "x-portkey-config"
      }
    ],
    "identity_injection": {
      "header_pair": {
        "customizable": true,
        "end_user_id_header": "x-bf-dim-netbird_user_id",
        "tags_header": "x-bf-dim-netbird_groups"
      },
      "json_metadata": {
        "customizable": true,
        "header": "cf-aig-metadata",
        "user_key": "netbird_user_id",
        "groups_key": "netbird_groups"
      }
    },
    "models": [
      {
        "id": "gpt-4o",
        "label": "GPT-4o",
        "input_per_1k": 0.005,
        "output_per_1k": 0.015,
        "context_window": 128000
      }
    ]
  }
]
GET/api/agent-network/providers

List all Agent Network Providers

Returns a list of all Agent Network AI providers configured for the account.

Request

GET
/api/agent-network/providers
curl -X GET https://api.netbird.io/api/agent-network/providers \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

[
  {
    "id": "ainp_d1m3kebd9pcs0c1pnu7g",
    "provider_id": "openai_api",
    "name": "OpenAI API",
    "upstream_url": "https://api.openai.com",
    "models": [
      {
        "id": "gpt-4o-mini",
        "input_per_1k": 0.00015,
        "output_per_1k": 0.0006
      }
    ],
    "extra_values": {
      "x-portkey-config": "pc-prod-3f2a"
    },
    "identity_header_user_id": "x-bf-dim-netbird_user_id",
    "identity_header_groups": "x-bf-dim-netbird_groups",
    "enabled": true,
    "created_at": "2026-04-26T10:30:00Z",
    "updated_at": "2026-04-26T10:30:00Z"
  }
]
POST/api/agent-network/providers

Create an Agent Network Provider

Connects a new Agent Network AI provider for the account.

Request-Body Parameters

  • Name
    provider_id
    Type
    string
    Required
    required
    Enum
    Description

    Catalog identifier for the upstream AI provider (e.g. openai_api, anthropic_api, azure_openai_api, bedrock_api, vertex_ai_api, mistral_api, custom).

  • Name
    name
    Type
    string
    Required
    required
    Enum
    Description

    Display name for the provider.

  • Name
    upstream_url
    Type
    string
    Required
    required
    Enum
    Description

    Full upstream URL (with scheme) that NetBird forwards traffic to.

  • Name
    bootstrap_cluster
    Type
    string
    Required
    optional
    Enum
    Description

    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.

  • Name
    api_key
    Type
    string
    Required
    optional
    Enum
    Description

    Upstream provider API key. Sealed at rest on the management server and never returned in responses. Required on create; optional on update (omit to keep the existing key).

  • Name
    models
    Type
    object[]
    Required
    optional
    Enum
    Description
    Models exposed through this endpoint, with the operator's per-1k input/output prices. Empty means all catalog models are allowed at catalog prices.
      • Name
        id
        Type
        string
        Required
        required
        Enum
        Description

        Model identifier (e.g. "gpt-4o-mini").

      • Name
        input_per_1k
        Type
        number
        Required
        required
        Enum
        Description

        Cost per 1k input tokens, in USD.

      • Name
        output_per_1k
        Type
        number
        Required
        required
        Enum
        Description

        Cost per 1k output tokens, in USD.

  • Name
    extra_values
    Type
    object
    Required
    optional
    Enum
    Description

    Operator-typed values for catalog-declared extra headers (see AgentNetworkProvider.extra_values). When present on a request, the whole map replaces the stored values. Empty strings drop the corresponding key.

  • Name
    identity_header_user_id
    Type
    string
    Required
    optional
    Enum
    Description

    Wire header name for the caller's display identity. See AgentNetworkProvider.identity_header_user_id. When omitted on a request, the stored value is left unchanged; pass an empty string explicitly to clear it (which disables stamping for this dimension).

  • Name
    identity_header_groups
    Type
    string
    Required
    optional
    Enum
    Description

    Wire header name for the caller's groups CSV. See AgentNetworkProvider.identity_header_groups. Same omit / empty semantics as identity_header_user_id.

  • Name
    enabled
    Type
    boolean
    Required
    optional
    Enum
    Description

    Whether the provider is enabled. Defaults to true on create.

Request

POST
/api/agent-network/providers
curl -X POST https://api.netbird.io/api/agent-network/providers \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Token <TOKEN>' \
--data-raw '{
  "provider_id": "openai_api",
  "name": "OpenAI API",
  "upstream_url": "https://api.openai.com",
  "bootstrap_cluster": "eu.proxy.netbird.io",
  "api_key": "sk-...",
  "models": [
    {
      "id": "gpt-4o-mini",
      "input_per_1k": 0.00015,
      "output_per_1k": 0.0006
    }
  ],
  "extra_values": {
    "x-portkey-config": "pc-prod-3f2a"
  },
  "identity_header_user_id": "x-bf-dim-netbird_user_id",
  "identity_header_groups": "x-bf-dim-netbird_groups",
  "enabled": true
}'

Response

{
  "id": "ainp_d1m3kebd9pcs0c1pnu7g",
  "provider_id": "openai_api",
  "name": "OpenAI API",
  "upstream_url": "https://api.openai.com",
  "models": [
    {
      "id": "gpt-4o-mini",
      "input_per_1k": 0.00015,
      "output_per_1k": 0.0006
    }
  ],
  "extra_values": {
    "x-portkey-config": "pc-prod-3f2a"
  },
  "identity_header_user_id": "x-bf-dim-netbird_user_id",
  "identity_header_groups": "x-bf-dim-netbird_groups",
  "enabled": true,
  "created_at": "2026-04-26T10:30:00Z",
  "updated_at": "2026-04-26T10:30:00Z"
}
GET/api/agent-network/providers/{providerId}

Retrieve an Agent Network Provider

Get information about a specific Agent Network AI provider.

Path Parameters

  • Name
    providerId
    Type
    string
    Required
    required
    Enum
    Description

    The unique identifier of an Agent Network provider

Request

GET
/api/agent-network/providers/{providerId}
curl -X GET https://api.netbird.io/api/agent-network/providers/{providerId} \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

{
  "id": "ainp_d1m3kebd9pcs0c1pnu7g",
  "provider_id": "openai_api",
  "name": "OpenAI API",
  "upstream_url": "https://api.openai.com",
  "models": [
    {
      "id": "gpt-4o-mini",
      "input_per_1k": 0.00015,
      "output_per_1k": 0.0006
    }
  ],
  "extra_values": {
    "x-portkey-config": "pc-prod-3f2a"
  },
  "identity_header_user_id": "x-bf-dim-netbird_user_id",
  "identity_header_groups": "x-bf-dim-netbird_groups",
  "enabled": true,
  "created_at": "2026-04-26T10:30:00Z",
  "updated_at": "2026-04-26T10:30:00Z"
}
PUT/api/agent-network/providers/{providerId}

Update an Agent Network Provider

Update an existing Agent Network AI provider.

Path Parameters

  • Name
    providerId
    Type
    string
    Required
    required
    Enum
    Description

    The unique identifier of an Agent Network provider

Request-Body Parameters

  • Name
    provider_id
    Type
    string
    Required
    required
    Enum
    Description

    Catalog identifier for the upstream AI provider (e.g. openai_api, anthropic_api, azure_openai_api, bedrock_api, vertex_ai_api, mistral_api, custom).

  • Name
    name
    Type
    string
    Required
    required
    Enum
    Description

    Display name for the provider.

  • Name
    upstream_url
    Type
    string
    Required
    required
    Enum
    Description

    Full upstream URL (with scheme) that NetBird forwards traffic to.

  • Name
    bootstrap_cluster
    Type
    string
    Required
    optional
    Enum
    Description

    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.

  • Name
    api_key
    Type
    string
    Required
    optional
    Enum
    Description

    Upstream provider API key. Sealed at rest on the management server and never returned in responses. Required on create; optional on update (omit to keep the existing key).

  • Name
    models
    Type
    object[]
    Required
    optional
    Enum
    Description
    Models exposed through this endpoint, with the operator's per-1k input/output prices. Empty means all catalog models are allowed at catalog prices.
      • Name
        id
        Type
        string
        Required
        required
        Enum
        Description

        Model identifier (e.g. "gpt-4o-mini").

      • Name
        input_per_1k
        Type
        number
        Required
        required
        Enum
        Description

        Cost per 1k input tokens, in USD.

      • Name
        output_per_1k
        Type
        number
        Required
        required
        Enum
        Description

        Cost per 1k output tokens, in USD.

  • Name
    extra_values
    Type
    object
    Required
    optional
    Enum
    Description

    Operator-typed values for catalog-declared extra headers (see AgentNetworkProvider.extra_values). When present on a request, the whole map replaces the stored values. Empty strings drop the corresponding key.

  • Name
    identity_header_user_id
    Type
    string
    Required
    optional
    Enum
    Description

    Wire header name for the caller's display identity. See AgentNetworkProvider.identity_header_user_id. When omitted on a request, the stored value is left unchanged; pass an empty string explicitly to clear it (which disables stamping for this dimension).

  • Name
    identity_header_groups
    Type
    string
    Required
    optional
    Enum
    Description

    Wire header name for the caller's groups CSV. See AgentNetworkProvider.identity_header_groups. Same omit / empty semantics as identity_header_user_id.

  • Name
    enabled
    Type
    boolean
    Required
    optional
    Enum
    Description

    Whether the provider is enabled. Defaults to true on create.

Request

PUT
/api/agent-network/providers/{providerId}
curl -X PUT https://api.netbird.io/api/agent-network/providers/{providerId} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Token <TOKEN>' \
--data-raw '{
  "provider_id": "openai_api",
  "name": "OpenAI API",
  "upstream_url": "https://api.openai.com",
  "bootstrap_cluster": "eu.proxy.netbird.io",
  "api_key": "sk-...",
  "models": [
    {
      "id": "gpt-4o-mini",
      "input_per_1k": 0.00015,
      "output_per_1k": 0.0006
    }
  ],
  "extra_values": {
    "x-portkey-config": "pc-prod-3f2a"
  },
  "identity_header_user_id": "x-bf-dim-netbird_user_id",
  "identity_header_groups": "x-bf-dim-netbird_groups",
  "enabled": true
}'

Response

{
  "id": "ainp_d1m3kebd9pcs0c1pnu7g",
  "provider_id": "openai_api",
  "name": "OpenAI API",
  "upstream_url": "https://api.openai.com",
  "models": [
    {
      "id": "gpt-4o-mini",
      "input_per_1k": 0.00015,
      "output_per_1k": 0.0006
    }
  ],
  "extra_values": {
    "x-portkey-config": "pc-prod-3f2a"
  },
  "identity_header_user_id": "x-bf-dim-netbird_user_id",
  "identity_header_groups": "x-bf-dim-netbird_groups",
  "enabled": true,
  "created_at": "2026-04-26T10:30:00Z",
  "updated_at": "2026-04-26T10:30:00Z"
}
DELETE/api/agent-network/providers/{providerId}

Delete an Agent Network Provider

Delete an existing Agent Network AI provider.

Path Parameters

  • Name
    providerId
    Type
    string
    Required
    required
    Enum
    Description

    The unique identifier of an Agent Network provider

Request

DELETE
/api/agent-network/providers/{providerId}
curl -X DELETE https://api.netbird.io/api/agent-network/providers/{providerId} \
-H 'Authorization: Token <TOKEN>'
GET/api/agent-network/policies

List all Agent Network Policies

Returns a list of all Agent Network policies for the account.

Request

GET
/api/agent-network/policies
curl -X GET https://api.netbird.io/api/agent-network/policies \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

[
  {
    "id": "ainpol_d1m3kebd9pcs0c1pnu7g",
    "name": "Engineering → OpenAI",
    "description": "Engineers can call OpenAI under production guardrails.",
    "enabled": true,
    "source_groups": [
      "ch8vp3o6lnna9hg0sd8g"
    ],
    "destination_provider_ids": [
      "ainp_d1m3kebd9pcs0c1pnu7g"
    ],
    "guardrail_ids": [],
    "limits": {
      "token_limit": {
        "enabled": true,
        "group_cap": 10000000,
        "user_cap": 1000000,
        "window_seconds": 2592000
      },
      "budget_limit": {
        "enabled": true,
        "group_cap_usd": 1000,
        "user_cap_usd": 100,
        "window_seconds": 2592000
      }
    },
    "created_at": "2026-04-26T10:30:00Z",
    "updated_at": "2026-04-26T10:30:00Z"
  }
]
POST/api/agent-network/policies

Create an Agent Network Policy

Creates a new Agent Network policy binding source groups to destination providers, optionally enforced by guardrails.

Request-Body Parameters

  • Name
    name
    Type
    string
    Required
    required
    Enum
    Description

    Display name for the policy.

  • Name
    description
    Type
    string
    Required
    optional
    Enum
    Description

    Optional human-readable description.

  • Name
    enabled
    Type
    boolean
    Required
    optional
    Enum
    Description

    Whether the policy is enabled. Defaults to true on create.

  • Name
    source_groups
    Type
    string[]
    Required
    required
    Enum
    Description

    NetBird group ids whose members are allowed to call the destination providers.

  • Name
    destination_provider_ids
    Type
    string[]
    Required
    required
    Enum
    Description

    Agent Network provider ids the source groups can reach.

  • Name
    guardrail_ids
    Type
    string[]
    Required
    optional
    Enum
    Description

    Agent Network guardrail ids to attach to this policy.

  • Name
    limits
    Type
    object
    Required
    optional
    Enum
    Description
    Token and budget caps attached directly to the policy. These compose with any guardrail-level checks.
      • Name
        token_limit
        Type
        object
        Required
        required
        Enum
        Description
        Per-policy token cap. group_cap is applied to each source group independently — every group in the policy's source_groups gets its own bucket of this size. user_cap is applied independently to each individual user. Caps reset to zero at the start of each window.
          • Name
            enabled
            Type
            boolean
            Required
            required
            Enum
            Description
          • Name
            group_cap
            Type
            integer
            Required
            required
            Enum
            00
            Description

            Tokens allowed per source group within the window (each group has its own bucket of this size). 0 means uncapped.

          • Name
            user_cap
            Type
            integer
            Required
            required
            Enum
            00
            Description

            Tokens allowed per individual user within the window. 0 means uncapped.

          • Name
            window_seconds
            Type
            integer
            Required
            required
            Enum
            Possible Values: >=60
            Description

            Reset frequency in seconds. The cap counter resets to zero at the start of each window. Minimum 60 (one minute) when the limit is enabled.

      • Name
        budget_limit
        Type
        object
        Required
        required
        Enum
        Description
        Per-policy USD spend cap. group_cap_usd is applied to each source group independently — every group in the policy's source_groups gets its own bucket of this size. user_cap_usd is applied independently to each individual user. Caps reset to zero at the start of each window.
          • Name
            enabled
            Type
            boolean
            Required
            required
            Enum
            Description
          • Name
            group_cap_usd
            Type
            number
            Required
            required
            Enum
            00
            Description

            USD allowed per source group within the window (each group has its own bucket of this size). 0 means uncapped.

          • Name
            user_cap_usd
            Type
            number
            Required
            required
            Enum
            00
            Description

            USD allowed per individual user within the window. 0 means uncapped.

          • Name
            window_seconds
            Type
            integer
            Required
            required
            Enum
            Possible Values: >=60
            Description

            Reset frequency in seconds. Caps reset at the start of each window. Minimum 60 (one minute) when the limit is enabled.

Request

POST
/api/agent-network/policies
curl -X POST https://api.netbird.io/api/agent-network/policies \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Token <TOKEN>' \
--data-raw '{
  "name": "Engineering → OpenAI",
  "description": "Engineers can call OpenAI under production guardrails.",
  "enabled": true,
  "source_groups": [
    "ch8vp3o6lnna9hg0sd8g"
  ],
  "destination_provider_ids": [
    "ainp_d1m3kebd9pcs0c1pnu7g"
  ],
  "guardrail_ids": [],
  "limits": {
    "token_limit": {
      "enabled": true,
      "group_cap": 10000000,
      "user_cap": 1000000,
      "window_seconds": 2592000
    },
    "budget_limit": {
      "enabled": true,
      "group_cap_usd": 1000,
      "user_cap_usd": 100,
      "window_seconds": 2592000
    }
  }
}'

Response

{
  "id": "ainpol_d1m3kebd9pcs0c1pnu7g",
  "name": "Engineering → OpenAI",
  "description": "Engineers can call OpenAI under production guardrails.",
  "enabled": true,
  "source_groups": [
    "ch8vp3o6lnna9hg0sd8g"
  ],
  "destination_provider_ids": [
    "ainp_d1m3kebd9pcs0c1pnu7g"
  ],
  "guardrail_ids": [],
  "limits": {
    "token_limit": {
      "enabled": true,
      "group_cap": 10000000,
      "user_cap": 1000000,
      "window_seconds": 2592000
    },
    "budget_limit": {
      "enabled": true,
      "group_cap_usd": 1000,
      "user_cap_usd": 100,
      "window_seconds": 2592000
    }
  },
  "created_at": "2026-04-26T10:30:00Z",
  "updated_at": "2026-04-26T10:30:00Z"
}
GET/api/agent-network/policies/{policyId}

Retrieve an Agent Network Policy

Get information about a specific Agent Network policy.

Path Parameters

  • Name
    policyId
    Type
    string
    Required
    required
    Enum
    Description

    The unique identifier of an Agent Network policy

Request

GET
/api/agent-network/policies/{policyId}
curl -X GET https://api.netbird.io/api/agent-network/policies/{policyId} \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

{
  "id": "ainpol_d1m3kebd9pcs0c1pnu7g",
  "name": "Engineering → OpenAI",
  "description": "Engineers can call OpenAI under production guardrails.",
  "enabled": true,
  "source_groups": [
    "ch8vp3o6lnna9hg0sd8g"
  ],
  "destination_provider_ids": [
    "ainp_d1m3kebd9pcs0c1pnu7g"
  ],
  "guardrail_ids": [],
  "limits": {
    "token_limit": {
      "enabled": true,
      "group_cap": 10000000,
      "user_cap": 1000000,
      "window_seconds": 2592000
    },
    "budget_limit": {
      "enabled": true,
      "group_cap_usd": 1000,
      "user_cap_usd": 100,
      "window_seconds": 2592000
    }
  },
  "created_at": "2026-04-26T10:30:00Z",
  "updated_at": "2026-04-26T10:30:00Z"
}
PUT/api/agent-network/policies/{policyId}

Update an Agent Network Policy

Update an existing Agent Network policy.

Path Parameters

  • Name
    policyId
    Type
    string
    Required
    required
    Enum
    Description

    The unique identifier of an Agent Network policy

Request-Body Parameters

  • Name
    name
    Type
    string
    Required
    required
    Enum
    Description

    Display name for the policy.

  • Name
    description
    Type
    string
    Required
    optional
    Enum
    Description

    Optional human-readable description.

  • Name
    enabled
    Type
    boolean
    Required
    optional
    Enum
    Description

    Whether the policy is enabled. Defaults to true on create.

  • Name
    source_groups
    Type
    string[]
    Required
    required
    Enum
    Description

    NetBird group ids whose members are allowed to call the destination providers.

  • Name
    destination_provider_ids
    Type
    string[]
    Required
    required
    Enum
    Description

    Agent Network provider ids the source groups can reach.

  • Name
    guardrail_ids
    Type
    string[]
    Required
    optional
    Enum
    Description

    Agent Network guardrail ids to attach to this policy.

  • Name
    limits
    Type
    object
    Required
    optional
    Enum
    Description
    Token and budget caps attached directly to the policy. These compose with any guardrail-level checks.
      • Name
        token_limit
        Type
        object
        Required
        required
        Enum
        Description
        Per-policy token cap. group_cap is applied to each source group independently — every group in the policy's source_groups gets its own bucket of this size. user_cap is applied independently to each individual user. Caps reset to zero at the start of each window.
          • Name
            enabled
            Type
            boolean
            Required
            required
            Enum
            Description
          • Name
            group_cap
            Type
            integer
            Required
            required
            Enum
            00
            Description

            Tokens allowed per source group within the window (each group has its own bucket of this size). 0 means uncapped.

          • Name
            user_cap
            Type
            integer
            Required
            required
            Enum
            00
            Description

            Tokens allowed per individual user within the window. 0 means uncapped.

          • Name
            window_seconds
            Type
            integer
            Required
            required
            Enum
            Possible Values: >=60
            Description

            Reset frequency in seconds. The cap counter resets to zero at the start of each window. Minimum 60 (one minute) when the limit is enabled.

      • Name
        budget_limit
        Type
        object
        Required
        required
        Enum
        Description
        Per-policy USD spend cap. group_cap_usd is applied to each source group independently — every group in the policy's source_groups gets its own bucket of this size. user_cap_usd is applied independently to each individual user. Caps reset to zero at the start of each window.
          • Name
            enabled
            Type
            boolean
            Required
            required
            Enum
            Description
          • Name
            group_cap_usd
            Type
            number
            Required
            required
            Enum
            00
            Description

            USD allowed per source group within the window (each group has its own bucket of this size). 0 means uncapped.

          • Name
            user_cap_usd
            Type
            number
            Required
            required
            Enum
            00
            Description

            USD allowed per individual user within the window. 0 means uncapped.

          • Name
            window_seconds
            Type
            integer
            Required
            required
            Enum
            Possible Values: >=60
            Description

            Reset frequency in seconds. Caps reset at the start of each window. Minimum 60 (one minute) when the limit is enabled.

Request

PUT
/api/agent-network/policies/{policyId}
curl -X PUT https://api.netbird.io/api/agent-network/policies/{policyId} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Token <TOKEN>' \
--data-raw '{
  "name": "Engineering → OpenAI",
  "description": "Engineers can call OpenAI under production guardrails.",
  "enabled": true,
  "source_groups": [
    "ch8vp3o6lnna9hg0sd8g"
  ],
  "destination_provider_ids": [
    "ainp_d1m3kebd9pcs0c1pnu7g"
  ],
  "guardrail_ids": [],
  "limits": {
    "token_limit": {
      "enabled": true,
      "group_cap": 10000000,
      "user_cap": 1000000,
      "window_seconds": 2592000
    },
    "budget_limit": {
      "enabled": true,
      "group_cap_usd": 1000,
      "user_cap_usd": 100,
      "window_seconds": 2592000
    }
  }
}'

Response

{
  "id": "ainpol_d1m3kebd9pcs0c1pnu7g",
  "name": "Engineering → OpenAI",
  "description": "Engineers can call OpenAI under production guardrails.",
  "enabled": true,
  "source_groups": [
    "ch8vp3o6lnna9hg0sd8g"
  ],
  "destination_provider_ids": [
    "ainp_d1m3kebd9pcs0c1pnu7g"
  ],
  "guardrail_ids": [],
  "limits": {
    "token_limit": {
      "enabled": true,
      "group_cap": 10000000,
      "user_cap": 1000000,
      "window_seconds": 2592000
    },
    "budget_limit": {
      "enabled": true,
      "group_cap_usd": 1000,
      "user_cap_usd": 100,
      "window_seconds": 2592000
    }
  },
  "created_at": "2026-04-26T10:30:00Z",
  "updated_at": "2026-04-26T10:30:00Z"
}
DELETE/api/agent-network/policies/{policyId}

Delete an Agent Network Policy

Delete an existing Agent Network policy.

Path Parameters

  • Name
    policyId
    Type
    string
    Required
    required
    Enum
    Description

    The unique identifier of an Agent Network policy

Request

DELETE
/api/agent-network/policies/{policyId}
curl -X DELETE https://api.netbird.io/api/agent-network/policies/{policyId} \
-H 'Authorization: Token <TOKEN>'
GET/api/agent-network/guardrails

List all Agent Network Guardrails

Returns a list of all Agent Network guardrails for the account.

Request

GET
/api/agent-network/guardrails
curl -X GET https://api.netbird.io/api/agent-network/guardrails \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

[
  {
    "id": "ainguard_d1m3kebd9pcs0c1pnu7g",
    "name": "Strict — Production",
    "description": "Tight model allowlist, PII redaction, hard monthly budget.",
    "checks": {
      "model_allowlist": {
        "enabled": true,
        "models": [
          "gpt-4o-mini",
          "claude-haiku-4-5"
        ]
      },
      "prompt_capture": {
        "enabled": true,
        "redact_pii": true
      }
    },
    "created_at": "2026-04-26T10:30:00Z",
    "updated_at": "2026-04-26T10:30:00Z"
  }
]
POST/api/agent-network/guardrails

Create an Agent Network Guardrail

Creates a new Agent Network guardrail that can be attached to one or more policies.

Request-Body Parameters

  • Name
    name
    Type
    string
    Required
    required
    Enum
    Description

    Display name for the guardrail.

  • Name
    description
    Type
    string
    Required
    optional
    Enum
    Description

    Optional human-readable description.

  • Name
    checks
    Type
    object
    Required
    required
    Enum
    Description
    Guardrail check parameters. Each entry has an enabled flag plus per-check configuration; disabled entries are inert.
      • Name
        model_allowlist
        Type
        object
        Required
        required
        Enum
        Description
        More Information
          • Name
            enabled
            Type
            boolean
            Required
            required
            Enum
            Description
          • Name
            models
            Type
            string[]
            Required
            required
            Enum
            Description

            Allowed catalog model ids. Requests for any other model are denied.

      • Name
        prompt_capture
        Type
        object
        Required
        required
        Enum
        Description
        More Information
          • Name
            enabled
            Type
            boolean
            Required
            required
            Enum
            Description
          • Name
            redact_pii
            Type
            boolean
            Required
            required
            Enum
            Description

Request

POST
/api/agent-network/guardrails
curl -X POST https://api.netbird.io/api/agent-network/guardrails \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Token <TOKEN>' \
--data-raw '{
  "name": "Strict — Production",
  "description": "Tight model allowlist, PII redaction, hard monthly budget.",
  "checks": {
    "model_allowlist": {
      "enabled": true,
      "models": [
        "gpt-4o-mini",
        "claude-haiku-4-5"
      ]
    },
    "prompt_capture": {
      "enabled": true,
      "redact_pii": true
    }
  }
}'

Response

{
  "id": "ainguard_d1m3kebd9pcs0c1pnu7g",
  "name": "Strict — Production",
  "description": "Tight model allowlist, PII redaction, hard monthly budget.",
  "checks": {
    "model_allowlist": {
      "enabled": true,
      "models": [
        "gpt-4o-mini",
        "claude-haiku-4-5"
      ]
    },
    "prompt_capture": {
      "enabled": true,
      "redact_pii": true
    }
  },
  "created_at": "2026-04-26T10:30:00Z",
  "updated_at": "2026-04-26T10:30:00Z"
}
GET/api/agent-network/guardrails/{guardrailId}

Retrieve an Agent Network Guardrail

Get information about a specific Agent Network guardrail.

Path Parameters

  • Name
    guardrailId
    Type
    string
    Required
    required
    Enum
    Description

    The unique identifier of an Agent Network guardrail

Request

GET
/api/agent-network/guardrails/{guardrailId}
curl -X GET https://api.netbird.io/api/agent-network/guardrails/{guardrailId} \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

{
  "id": "ainguard_d1m3kebd9pcs0c1pnu7g",
  "name": "Strict — Production",
  "description": "Tight model allowlist, PII redaction, hard monthly budget.",
  "checks": {
    "model_allowlist": {
      "enabled": true,
      "models": [
        "gpt-4o-mini",
        "claude-haiku-4-5"
      ]
    },
    "prompt_capture": {
      "enabled": true,
      "redact_pii": true
    }
  },
  "created_at": "2026-04-26T10:30:00Z",
  "updated_at": "2026-04-26T10:30:00Z"
}
PUT/api/agent-network/guardrails/{guardrailId}

Update an Agent Network Guardrail

Update an existing Agent Network guardrail.

Path Parameters

  • Name
    guardrailId
    Type
    string
    Required
    required
    Enum
    Description

    The unique identifier of an Agent Network guardrail

Request-Body Parameters

  • Name
    name
    Type
    string
    Required
    required
    Enum
    Description

    Display name for the guardrail.

  • Name
    description
    Type
    string
    Required
    optional
    Enum
    Description

    Optional human-readable description.

  • Name
    checks
    Type
    object
    Required
    required
    Enum
    Description
    Guardrail check parameters. Each entry has an enabled flag plus per-check configuration; disabled entries are inert.
      • Name
        model_allowlist
        Type
        object
        Required
        required
        Enum
        Description
        More Information
          • Name
            enabled
            Type
            boolean
            Required
            required
            Enum
            Description
          • Name
            models
            Type
            string[]
            Required
            required
            Enum
            Description

            Allowed catalog model ids. Requests for any other model are denied.

      • Name
        prompt_capture
        Type
        object
        Required
        required
        Enum
        Description
        More Information
          • Name
            enabled
            Type
            boolean
            Required
            required
            Enum
            Description
          • Name
            redact_pii
            Type
            boolean
            Required
            required
            Enum
            Description

Request

PUT
/api/agent-network/guardrails/{guardrailId}
curl -X PUT https://api.netbird.io/api/agent-network/guardrails/{guardrailId} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Token <TOKEN>' \
--data-raw '{
  "name": "Strict — Production",
  "description": "Tight model allowlist, PII redaction, hard monthly budget.",
  "checks": {
    "model_allowlist": {
      "enabled": true,
      "models": [
        "gpt-4o-mini",
        "claude-haiku-4-5"
      ]
    },
    "prompt_capture": {
      "enabled": true,
      "redact_pii": true
    }
  }
}'

Response

{
  "id": "ainguard_d1m3kebd9pcs0c1pnu7g",
  "name": "Strict — Production",
  "description": "Tight model allowlist, PII redaction, hard monthly budget.",
  "checks": {
    "model_allowlist": {
      "enabled": true,
      "models": [
        "gpt-4o-mini",
        "claude-haiku-4-5"
      ]
    },
    "prompt_capture": {
      "enabled": true,
      "redact_pii": true
    }
  },
  "created_at": "2026-04-26T10:30:00Z",
  "updated_at": "2026-04-26T10:30:00Z"
}
DELETE/api/agent-network/guardrails/{guardrailId}

Delete an Agent Network Guardrail

Delete an existing Agent Network guardrail.

Path Parameters

  • Name
    guardrailId
    Type
    string
    Required
    required
    Enum
    Description

    The unique identifier of an Agent Network guardrail

Request

DELETE
/api/agent-network/guardrails/{guardrailId}
curl -X DELETE https://api.netbird.io/api/agent-network/guardrails/{guardrailId} \
-H 'Authorization: Token <TOKEN>'