NetBird Read-Only MCP Preview
POST/api/routes

Create a route

Creates a route configuration for routing traffic through specified peers or peer groups. Supply the required route fields, and use either network or domains to define the route destination; those fields conflict with each other.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

13 body fields

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 created 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 schema requires id, description, network_id, enabled, metric, masquerade, groups, and keep_route; metric must be between 1 and 9999, and network_id must contain 1 to 40 characters. domains and network cannot be supplied together, and peer and peer_groups cannot be supplied together.