DNS API

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

GET /api/dns/nameservers

curl -X GET https://api.netbird.io/api/dns/nameservers \
  -H "Authorization: Token nbp_YOUR_TOKEN"

[
  {
    "id": "ch8i4ug6lnn4g9hqv7m0",
    "name": "Google DNS",
    "description": "Google public DNS servers",
    "nameservers": [
      {
        "ip": "8.8.8.8",
        "ns_type": "udp",
        "port": 53
      },
      {
        "ip": "8.8.4.4",
        "ns_type": "udp",
        "port": 53
      }
    ],
    "enabled": true,
    "groups": ["ch8i4ug6lnn4g9hqv7m1"],
    "primary": false,
    "domains": ["example.com"],
    "search_domains_enabled": true
  }
]

string

Unique nameserver group identifier

string

Nameserver group name (1-40 characters)

string

Description of the nameserver group

array

List of nameserver configurations (1-3 servers)

boolean

Whether the nameserver group is active

array

Peer group IDs that should use these nameservers

boolean

Primary nameserver group resolves all domains (requires empty domains)

array

Match domain list (empty only if primary: true)

boolean

Enable search domains (only when domains is not empty)

Create a Nameserver Group

POST /api/dns/nameservers

string

required

Nameserver group name (1-40 characters)

string

required

Description of the nameserver group

array

required

List of 1-3 nameserver configurations

boolean

required

Whether the nameserver group is active

array

required

Peer group IDs that should use these nameservers

boolean

required

Whether this is the primary nameserver group

array

required

Match domain list (1-255 characters each)

boolean

required

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

curl -X POST https://api.netbird.io/api/dns/nameservers \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate DNS",
    "description": "Internal corporate nameservers",
    "nameservers": [
      {"ip": "10.0.1.53", "ns_type": "udp", "port": 53}
    ],
    "enabled": true,
    "groups": ["ch8i4ug6lnn4g9hqv7m0"],
    "primary": false,
    "domains": ["corp.example.com", "internal.example.com"],
    "search_domains_enabled": true
  }'

Update a Nameserver Group

PUT /api/dns/nameservers/{nsgroupId}

string

required

The unique identifier of the nameserver group

Example

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}

Example

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

GET /api/dns/settings

Example

curl -X GET https://api.netbird.io/api/dns/settings \
  -H "Authorization: Token nbp_YOUR_TOKEN"

array

Group IDs whose DNS management is disabled

Update DNS Settings

PUT /api/dns/settings

array

required

Group IDs to disable DNS management for

Example

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

GET /api/dns/zones

curl -X GET https://api.netbird.io/api/dns/zones \
  -H "Authorization: Token nbp_YOUR_TOKEN"

[
  {
    "id": "ch8i4ug6lnn4g9hqv7m0",
    "name": "Internal Zone",
    "domain": "internal.company.com",
    "enabled": true,
    "enable_search_domain": false,
    "distribution_groups": ["ch8i4ug6lnn4g9hqv7m1"],
    "records": [
      {
        "id": "rec_123",
        "name": "app.internal.company.com",
        "type": "A",
        "content": "192.168.1.10",
        "ttl": 300
      }
    ]
  }
]

Create a DNS Zone

POST /api/dns/zones

string

required

Zone name identifier (1-255 characters)

string

required

Zone domain (FQDN)

boolean

required

Enable this zone as a search domain

array

required

Group IDs that will use this zone

Example

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

string

required

The unique identifier of the zone

string

required

FQDN for the DNS record (must be subdomain of zone)

string

required

DNS record type: A, AAAA, or CNAME

string

required

DNS record content (IP for A/AAAA, domain for CNAME)

integer

required

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

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": "www.internal.company.com",
    "type": "CNAME",
    "content": "api.internal.company.com",
    "ttl": 600
  }'

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
}

Allows 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

Getting Started

Resources

Nameserver Groups

List All Nameserver Groups

Create a Nameserver Group

Update a Nameserver Group

Delete a Nameserver Group

DNS Settings

Get DNS Settings

Update DNS Settings

Custom DNS Zones

List All DNS Zones

Create a DNS Zone

Update a DNS Zone

Delete a DNS Zone

DNS Records

Create a DNS Record

Update a DNS Record

Delete a DNS Record

DNS Resolution Flow

Common Configurations

Split DNS

Search Domains

Best Practices

​Nameserver Groups

​List All Nameserver Groups

​Create a Nameserver Group

​Update a Nameserver Group

​Delete a Nameserver Group

​DNS Settings

​Get DNS Settings

​Update DNS Settings

​Custom DNS Zones

​List All DNS Zones

​Create a DNS Zone

​Update a DNS Zone

​Delete a DNS Zone

​DNS Records

​Create a DNS Record

​Update a DNS Record

​Delete a DNS Record

​DNS Resolution Flow

​Common Configurations

​Split DNS

​Search Domains

​Best Practices

Nameserver Groups

List All Nameserver Groups

Create a Nameserver Group

Update a Nameserver Group

Delete a Nameserver Group

DNS Settings

Get DNS Settings

Update DNS Settings

Custom DNS Zones

List All DNS Zones

Create a DNS Zone

Update a DNS Zone

Delete a DNS Zone

DNS Records

Create a DNS Record

Update a DNS Record

Delete a DNS Record

DNS Resolution Flow

Common Configurations

Split DNS

Search Domains

Best Practices