NetBird Full API Reference + Read-Only MCP Prototype
PUT/api/agent-network/policies/{policyId}

Replace an Agent Network policy

Replaces an existing Agent Network policy. When you submit a body, include name, source_groups, and destination_provider_ids; each of the two arrays must contain at least one ID.

1 parameter · 7 body fields
policyIdstringrequired
The unique identifier of the Agent Network policy to replace.

Policy replacement details. If you provide a body, name, source_groups, and destination_provider_ids are required.

descriptionstringoptional
Optional human-readable description.
destination_provider_idsarray<string>required
Agent Network provider ids the source groups can reach.
enabledbooleanoptional
Whether the policy is enabled. Defaults to true on create.
guardrail_idsarray<string>optional
Agent Network guardrail ids to attach to this policy.
limitsobjectoptional
Token and budget caps attached directly to the policy. These compose with any guardrail-level checks.
namestringrequired
Display name for the policy.
source_groupsarray<string>required
NetBird group ids whose members are allowed to call the destination providers.

7 status codes
200Returns the updated policy object, including its ID, name, description, enabled state, source groups, destination providers, guardrails, limits, and creation and update timestamps.
created_atstringrequired
Timestamp when the policy was created.
descriptionstringrequired
Optional human-readable description.
destination_provider_idsarray<string>required
Agent Network provider ids (returned by the providers API) the source groups can reach.
enabledbooleanrequired
Whether the policy is enabled.
guardrail_idsarray<string>required
Agent Network guardrail ids attached to this policy.
idstringrequired
Policy ID
limitsobjectrequired
Token and budget caps attached directly to the policy. These compose with any guardrail-level checks.
namestringrequired
Display name for the policy.
source_groupsarray<string>required
NetBird group ids whose members are allowed to call the destination providers.
updated_atstringrequired
Timestamp when the policy was last updated.
400Returned when the request is invalid.
401Returned when authentication is missing or invalid.
403Returned when the authenticated user is not permitted to update the policy.
404Returned when the policy does not exist.
409Returned when the update conflicts with the current state.
messagestringoptional
A human-readable error message.
500Returned when an internal server error occurs.

Error handling

A 400 indicates an invalid request, a 401 indicates missing or invalid authentication, and a 403 indicates insufficient permission. A 404 indicates that the policy was not found, a 409 indicates a conflict, and a 500 indicates an internal server error. The policyId path parameter must identify an existing policy; if you provide a body, include name, source_groups, and destination_provider_ids, with at least one item in each array, and include both token_limit and budget_limit if you provide limits.