Skip to main content
The Routes API allows you to configure network routes, enabling peers to access external networks, subnets, or act as exit nodes for internet traffic.

​
List All Routes

Returns a list of all configured routes. 
GET /api/routes

curl -X GET https://api.netbird.io/api/routes \
  -H "Authorization: Token nbp_YOUR_TOKEN"
​
id
string
Unique route identifier
​
network_id
string
Route network identifier for grouping HA routes
​
network_type
string
Network type: IPv4, IPv6, or domain
​
description
string
Route description
​
enabled
boolean
Whether the route is active
​
peer
string
Peer ID acting as the routing peer
​
peer_groups
array
Peer group IDs for HA routing (alternative to peer)
​
network
string
Network range in CIDR format (conflicts with domains)
​
domains
array
Domain list to dynamically resolve (max 32, conflicts with network)
​
metric
integer
Route priority (lower number = higher priority, range: 1-9999)
​
masquerade
boolean
Whether to masquerade (NAT) traffic to this route
​
groups
array
Group IDs that can use this route
​
keep_route
boolean
Keep route after domain resolution fails
​
access_control_groups
array
Group IDs with access control permissions

​
Get a Route

Retrieve detailed information about a specific route. 
GET /api/routes/{routeId}
​
routeId
string
required
The unique identifier of the route
Example
curl -X GET https://api.netbird.io/api/routes/chacdk86lnnboviihd7g \
  -H "Authorization: Token nbp_YOUR_TOKEN"

​
Create a Route

Create a new network route. 
POST /api/routes
​
description
string
required
Route description
​
network_id
string
required
Network identifier for grouping HA routes (1-40 characters)
​
enabled
boolean
required
Whether the route is active
​
peer
string
Peer ID to use as routing peer (cannot be used with peer_groups)
​
peer_groups
array
Peer group IDs for HA routing (cannot be used with peer)
​
network
string
Network range in CIDR format (cannot be used with domains)
​
domains
array
List of domains to resolve (max 32, cannot be used with network)
​
metric
integer
required
Route priority (1-9999, lower = higher priority)
​
masquerade
boolean
required
Enable NAT for traffic to this route
​
groups
array
required
Group IDs that can use this route
​
keep_route
boolean
required
Keep route after domain resolution fails
​
access_control_groups
array
Group IDs with access control permissions
​
skip_auto_apply
boolean
Skip auto-application for exit node routes (0.0.0.0/0)
curl -X POST https://api.netbird.io/api/routes \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Office Network",
    "network_id": "office-lan",
    "enabled": true,
    "peer": "chacbco6lnnbn6cg5s91",
    "network": "192.168.1.0/24",
    "metric": 100,
    "masquerade": true,
    "groups": ["ch8i4ug6lnn4g9hqv7m0"],
    "keep_route": false
  }'

​
Update a Route

Update an existing route configuration. 
PUT /api/routes/{routeId}
​
routeId
string
required
The unique identifier of the route
Example
curl -X PUT https://api.netbird.io/api/routes/chacdk86lnnboviihd7g \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated Office Network",
    "network_id": "office-lan",
    "enabled": true,
    "peer": "chacbco6lnnbn6cg5s91",
    "network": "192.168.1.0/24",
    "metric": 50,
    "masquerade": true,
    "groups": ["ch8i4ug6lnn4g9hqv7m0"],
    "keep_route": false
  }'

​
Delete a Route

Remove a route from the network. 
DELETE /api/routes/{routeId}
​
routeId
string
required
The unique identifier of the route
Example
curl -X DELETE https://api.netbird.io/api/routes/chacdk86lnnboviihd7g \
  -H "Authorization: Token nbp_YOUR_TOKEN"

​
Route Types

​
Subnet Routes

Route traffic to specific IP subnets: 
{
  "network": "10.0.0.0/16",
  "description": "AWS VPC"
}
Use cases:
  • Access cloud VPCs
  • Connect to office LANs
  • Reach private data centers

​
Domain Routes

Dynamically route traffic to resolved domains: 
{
  "domains": ["*.internal.company.com", "api.example.com"],
  "keep_route": true
}
Use cases:
  • Route to dynamic cloud services
  • Access internal services by domain
  • Support wildcard domain routing
Domain routes are resolved periodically. Set keep_route: true to maintain connectivity even if resolution temporarily fails.

​
Exit Nodes

Route all internet traffic through a peer: 
{
  "network": "0.0.0.0/0",
  "masquerade": true,
  "metric": 9999
}
Use cases:
  • Secure public WiFi connections
  • Access region-specific content
  • Centralize internet egress

​
High Availability Routing

Use multiple routing peers for redundancy: 
{
  "network_id": "ha-route-1",
  "peer_groups": [
    "routing-peers-group-id"
  ],
  "network": "10.0.0.0/16"
}
Peers in the group automatically provide failover.

​
Route Priority

Control route selection with metrics:

High Priority

metric: 1-100Preferred routes

Medium Priority

metric: 101-1000Normal routes

Low Priority

metric: 1001-9999Backup/exit nodes

​
Masquerading (NAT)

Enable masquerading to NAT traffic: 
{
  "masquerade": true
}
Required when:
  • Routing peer doesn’t have routes back to NetBird network
  • Acting as an exit node
  • Accessing external networks that don’t know about NetBird IPs

​
Access Control

Limit which groups can use the route: 
{
  "groups": ["engineering-group-id"],
  "access_control_groups": ["admins-group-id"]
}
  • groups: Who can use the route
  • access_control_groups: Who can manage the route

​
Best Practices

Use specific metrics - Assign appropriate priorities based on route importance
Enable masquerading - Always enable for exit nodes and external networks
Group related routes - Use network_id to organize related routes
Use HA groups - Deploy multiple routing peers for critical routes
Monitor domain resolution - Check domain routes resolve correctly
Limit access - Only give route access to groups that need it

Build docs developers (and LLMs) love

Get started for freeTalk to us