The DNS API allows you to configure DNS nameservers, manage custom DNS zones, and control DNS settings for your NetBird network.
Nameserver Groups
Nameserver groups define DNS servers that peers should use for resolving domains.
List All Nameserver Groups
curl -X GET https://api.netbird.io/api/dns/nameservers \
-H "Authorization: Token nbp_YOUR_TOKEN"
Unique nameserver group identifier
Nameserver group name (1-40 characters)
Description of the nameserver group
List of nameserver configurations (1-3 servers)
Whether the nameserver group is active
Peer group IDs that should use these nameservers
Primary nameserver group resolves all domains (requires empty domains)
Match domain list (empty only if primary: true)
Enable search domains (only when domains is not empty)
Create a Nameserver Group
POST /api/dns/nameservers
Nameserver group name (1-40 characters)
Description of the nameserver group
List of 1-3 nameserver configurations
Whether the nameserver group is active
Peer group IDs that should use these nameservers
Whether this is the primary nameserver group
Match domain list (1-255 characters each)
Enable search domains for match domains
curl -X POST https://api.netbird.io/api/dns/nameservers \
-H "Authorization: Token nbp_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Cloudflare DNS",
"description": "Primary DNS using Cloudflare",
"nameservers": [
{"ip": "1.1.1.1", "ns_type": "udp", "port": 53},
{"ip": "1.0.0.1", "ns_type": "udp", "port": 53}
],
"enabled": true,
"groups": ["ch8i4ug6lnn4g9hqv7m0"],
"primary": true,
"domains": [],
"search_domains_enabled": false
}'
Update a Nameserver Group
PUT /api/dns/nameservers/{nsgroupId}
The unique identifier of the nameserver group
curl -X PUT https://api.netbird.io/api/dns/nameservers/ch8i4ug6lnn4g9hqv7m0 \
-H "Authorization: Token nbp_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated DNS",
"description": "Updated nameservers",
"nameservers": [...],
"enabled": true,
"groups": [...],
"primary": false,
"domains": ["example.com"],
"search_domains_enabled": true
}'
Delete a Nameserver Group
DELETE /api/dns/nameservers/{nsgroupId}
curl -X DELETE https://api.netbird.io/api/dns/nameservers/ch8i4ug6lnn4g9hqv7m0 \
-H "Authorization: Token nbp_YOUR_TOKEN"
DNS Settings
Manage global DNS settings including which groups have DNS management disabled.
Get DNS Settings
curl -X GET https://api.netbird.io/api/dns/settings \
-H "Authorization: Token nbp_YOUR_TOKEN"
disabled_management_groups
Group IDs whose DNS management is disabled
Update DNS Settings
disabled_management_groups
Group IDs to disable DNS management for
curl -X PUT https://api.netbird.io/api/dns/settings \
-H "Authorization: Token nbp_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"disabled_management_groups": ["ch8i4ug6lnn4g9hqv7m0"]
}'
Custom DNS Zones
Create custom DNS zones with A, AAAA, and CNAME records.
List All DNS Zones
curl -X GET https://api.netbird.io/api/dns/zones \
-H "Authorization: Token nbp_YOUR_TOKEN"
Create a DNS Zone
Zone name identifier (1-255 characters)
Enable this zone as a search domain
Group IDs that will use this zone
curl -X POST https://api.netbird.io/api/dns/zones \
-H "Authorization: Token nbp_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Internal Services",
"domain": "internal.company.com",
"enable_search_domain": true,
"distribution_groups": ["ch8i4ug6lnn4g9hqv7m0"]
}'
Update a DNS Zone
PUT /api/dns/zones/{zoneId}
Delete a DNS Zone
DELETE /api/dns/zones/{zoneId}
DNS Records
Manage DNS records within custom zones.
Create a DNS Record
POST /api/dns/zones/{zoneId}/records
The unique identifier of the zone
FQDN for the DNS record (must be subdomain of zone)
DNS record type: A, AAAA, or CNAME
DNS record content (IP for A/AAAA, domain for CNAME)
Time to live in seconds (minimum: 0)
curl -X POST https://api.netbird.io/api/dns/zones/zone_123/records \
-H "Authorization: Token nbp_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "api.internal.company.com",
"type": "A",
"content": "192.168.1.100",
"ttl": 300
}'
Update a DNS Record
PUT /api/dns/zones/{zoneId}/records/{recordId}
Delete a DNS Record
DELETE /api/dns/zones/{zoneId}/records/{recordId}
DNS Resolution Flow
- Custom Zones - Checked first for matching domains
- Domain-Specific Nameservers - Used for configured domains
- Primary Nameservers - Used for all other queries
- System DNS - Fallback if no NetBird DNS configured
Common Configurations
Split DNS
Use different nameservers for different domains:
[
{
"name": "Corporate DNS",
"primary": false,
"domains": ["corp.company.com"],
"nameservers": [{"ip": "10.0.1.53"}]
},
{
"name": "Public DNS",
"primary": true,
"domains": [],
"nameservers": [{"ip": "1.1.1.1"}]
}
]
Search Domains
Enable search domains for easy access:
{
"domains": ["company.com"],
"search_domains_enabled": true
}
ping server instead of ping server.company.com
Best Practices
Use primary nameservers - Always configure a primary for general DNS resolution
Split internal/external - Use separate nameservers for internal vs external domains
Enable search domains - Makes internal resources easier to access
Set appropriate TTLs - Lower for dynamic records, higher for static
Monitor DNS health - Ensure nameservers are reachable
