Routes API

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": "chacdk86lnnboviihd7g",
    "network_id": "aws-vpc-1",
    "network_type": "IPv4",
    "description": "AWS VPC Route",
    "enabled": true,
    "peer": "chacbco6lnnbn6cg5s91",
    "network": "10.0.0.0/16",
    "metric": 9999,
    "masquerade": true,
    "groups": ["ch8i4ug6lnn4g9hqv7m0"],
    "keep_route": false,
    "access_control_groups": ["chacbco6lnnbn6cg5s91"]
  }
]

string

Unique route identifier

string

Route network identifier for grouping HA routes

string

Network type: IPv4, IPv6, or domain

string

Route description

boolean

Whether the route is active

string

Peer ID acting as the routing peer

array

Peer group IDs for HA routing (alternative to peer)

string

Network range in CIDR format (conflicts with domains)

array

Domain list to dynamically resolve (max 32, conflicts with network)

integer

Route priority (lower number = higher priority, range: 1-9999)

boolean

Whether to masquerade (NAT) traffic to this route

array

Group IDs that can use this route

boolean

Keep route after domain resolution fails

array

Group IDs with access control permissions

Get a Route

Retrieve detailed information about a specific route.

GET /api/routes/{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

string

required

Route description

string

required

Network identifier for grouping HA routes (1-40 characters)

boolean

required

Whether the route is active

string

Peer ID to use as routing peer (cannot be used with peer_groups)

array

Peer group IDs for HA routing (cannot be used with peer)

string

Network range in CIDR format (cannot be used with domains)

array

List of domains to resolve (max 32, cannot be used with network)

integer

required

Route priority (1-9999, lower = higher priority)

boolean

required

Enable NAT for traffic to this route

array

required

Group IDs that can use this route

boolean

required

Keep route after domain resolution fails

array

Group IDs with access control permissions

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
  }'

curl -X POST https://api.netbird.io/api/routes \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "AWS Services",
    "network_id": "aws-services",
    "enabled": true,
    "peer": "chacbco6lnnbn6cg5s91",
    "domains": ["*.amazonaws.com", "*.aws.com"],
    "metric": 200,
    "masquerade": true,
    "groups": ["ch8i4ug6lnn4g9hqv7m0"],
    "keep_route": true
  }'

curl -X POST https://api.netbird.io/api/routes \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Exit Node - All Traffic",
    "network_id": "exit-node",
    "enabled": true,
    "peer": "chacbco6lnnbn6cg5s91",
    "network": "0.0.0.0/0",
    "metric": 9999,
    "masquerade": true,
    "groups": ["ch8i4ug6lnn4g9hqv7m0"],
    "keep_route": false,
    "skip_auto_apply": false
  }'

{
  "id": "chacdk86lnnboviihd7g",
  "network_id": "office-lan",
  "network_type": "IPv4",
  "description": "Office Network",
  "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}

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}

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

Getting Started

Resources

List All Routes

Get a Route

Create a Route

Update a Route

Delete a Route

Route Types

Subnet Routes

Domain Routes

Exit Nodes

High Availability Routing

Route Priority

High Priority

Medium Priority

Low Priority

Masquerading (NAT)

Access Control

Best Practices

​List All Routes

​Get a Route

​Create a Route

​Update a Route

​Delete a Route

​Route Types

​Subnet Routes

​Domain Routes

​Exit Nodes

​High Availability Routing

​Route Priority

High Priority

Medium Priority

Low Priority

​Masquerading (NAT)

​Access Control

​Best Practices

List All Routes

Get a Route

Create a Route

Update a Route

Delete a Route

Route Types

Subnet Routes

Domain Routes

Exit Nodes

High Availability Routing

Route Priority

Masquerading (NAT)

Access Control

Best Practices