NetBird Full API Reference + Read-Only MCP Prototype
PUT/api/routes/{routeId}

Replace a route configuration

Replaces the configuration of the route identified by its route ID. Supply the route fields required by the schema, and use either network or domains to define the destination because those fields conflict. The route's peer and peer_groups settings are also mutually exclusive.

1 parameter · 13 body fields
routeIdstringrequired
The unique identifier of the route to replace.

Replacement route configuration. The schema requires id, description, network_id, enabled, metric, masquerade, groups, and keep_route; id is required but has no property definition in the supplied schema.

access_control_groupsarray<string>optional
Access control group identifier associated with route.
descriptionstringrequired
Route description
domainsarray<string>optional
Domain list to be dynamically resolved. Max of 32 domains can be added per route configuration. Conflicts with network
enabledbooleanrequired
Route status
groupsarray<string>required
Group IDs containing routing peers
keep_routebooleanrequired
Indicate if the route should be kept after a domain doesn't resolve that IP anymore
masqueradebooleanrequired
Indicate if peer should masquerade traffic to this route's prefix
metricintegerrequired
Route metric number. Lowest number has higher priority
networkstringoptional
Network range in CIDR format, Conflicts with domains
network_idstringrequired
Route network identifier, to group HA routes
peerstringoptional
Peer Identifier associated with route. This property can not be set together with `peer_groups`
peer_groupsarray<string>optional
Peers Group Identifier associated with route. This property can not be set together with `peer`
skip_auto_applybooleanoptional
Indicate if this exit node route (0.0.0.0/0) should skip auto-application for client routing

5 status codes
200Returns the updated route object, including its identifier, network type, and route configuration.
idstringrequired
Route Id
network_typestringrequired
Network type indicating if it is a domain route or a IPv4/IPv6 route
access_control_groupsarray<string>optional
Access control group identifier associated with route.
descriptionstringrequired
Route description
domainsarray<string>optional
Domain list to be dynamically resolved. Max of 32 domains can be added per route configuration. Conflicts with network
enabledbooleanrequired
Route status
groupsarray<string>required
Group IDs containing routing peers
keep_routebooleanrequired
Indicate if the route should be kept after a domain doesn't resolve that IP anymore
masqueradebooleanrequired
Indicate if peer should masquerade traffic to this route's prefix
metricintegerrequired
Route metric number. Lowest number has higher priority
networkstringoptional
Network range in CIDR format, Conflicts with domains
network_idstringrequired
Route network identifier, to group HA routes
peerstringoptional
Peer Identifier associated with route. This property can not be set together with `peer_groups`
peer_groupsarray<string>optional
Peers Group Identifier associated with route. This property can not be set together with `peer`
skip_auto_applybooleanoptional
Indicate if this exit node route (0.0.0.0/0) should skip auto-application for client routing
400Returned when the request is malformed or a route value fails validation.
401Returned when authentication is required but missing or invalid.
403Returned when the operation is forbidden.
500Returned when an internal server error occurs.

Error handling

A 400 is returned for a malformed request, a 401 when authentication is required but missing or invalid, a 403 when the operation is forbidden, and a 500 for an internal server error. The routeId path parameter must identify the route to replace; the body schema requires id, description, network_id, enabled, metric, masquerade, groups, and keep_route. metric must be between 1 and 9999, network_id must contain 1 to 40 characters, and the conflicting field pairs network with domains and peer with peer_groups cannot be supplied together.