NetBird Full API Reference + Read-Only MCP Prototype
POST/api/dns/nameservers

Create a nameserver group

Creates a nameserver group with its nameservers, domain matches, and distribution groups. Supply all required fields, and set primary and domains consistently: a primary group should have no domains. A 200 response returns the created nameserver group.

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

8 body fields

Nameserver group configuration. Include all fields; each nameserver entry requires ip, ns_type, and port.

descriptionstringrequired
Description of the nameserver group
domainsarray<string>required
Match domain list. It should be empty only if primary is true.
enabledbooleanrequired
Nameserver group status
groupsarray<string>required
Distribution group IDs that defines group of peers that will use this nameserver group
namestringrequired
Name of nameserver group name
nameserversarray<object>required
Nameserver list
primarybooleanrequired
Defines if a nameserver group is primary that resolves all domains. It should be true only if domains list is empty.
search_domains_enabledbooleanrequired
Search domain status for match domains. It should be true only if domains list is not empty.

5 status codes
200Returns the created nameserver group object, including its identifier and configuration.
idstringrequired
Nameserver group ID
descriptionstringrequired
Description of the nameserver group
domainsarray<string>required
Match domain list. It should be empty only if primary is true.
enabledbooleanrequired
Nameserver group status
groupsarray<string>required
Distribution group IDs that defines group of peers that will use this nameserver group
namestringrequired
Name of nameserver group name
nameserversarray<object>required
Nameserver list
primarybooleanrequired
Defines if a nameserver group is primary that resolves all domains. It should be true only if domains list is empty.
search_domains_enabledbooleanrequired
Search domain status for match domains. It should be true only if domains list is not empty.
400Returned when the request is invalid or a required field or value fails validation.
401Returned when authentication is required but missing or invalid.
403Returned when the request is forbidden.
500Returned when an internal server error occurs.

Error handling

A 400 is returned when the request is invalid. A 401 is returned when authentication is missing or invalid. A 403 indicates insufficient permission, and a 500 indicates an internal server error. Include name, description, nameservers, enabled, groups, primary, domains, and search_domains_enabled; name must be 1–40 characters, each domain must be 1–255 characters, and nameservers must contain 1–3 entries with ns_type set to udp.