NetBird Full API Reference + Read-Only MCP Prototype
POST/api/reverse-proxies/domains

Create a Custom domain

Create a new Custom domain for use with service endpoints, this will trigger an initial validation check

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

2 body fields

Custom domain creation request

domainstringrequired
Domain name
target_clusterstringrequired
The proxy cluster this domain should be validated against

6 status codes
200Service created
access_groupsarray<string>optional
NetBird group IDs whose peers may reach this private service over the tunnel. Required when private=true; ignored otherwise. Mutually exclusive with bearer auth (SSO).
access_restrictionsobjectoptional
Connection-level access restrictions based on IP address or geography. Applies to both HTTP and L4 services.
authobjectrequired
domainstringrequired
Domain for the service
enabledbooleanrequired
Whether the service is enabled
idstringrequired
Service ID
listen_portintegeroptional
Port the proxy listens on (L4/TLS only)
metaobjectrequired
modestringoptional
Service mode. "http" for L7 reverse proxy, "tcp"/"udp"/"tls" for L4 passthrough.
Allowed:httptcpudptlsDefault:http
namestringrequired
Service name
pass_host_headerbooleanoptional
When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address
port_auto_assignedbooleanoptional
Whether the listen port was auto-assigned
privatebooleanoptional
When true, the service is NetBird-only — its target points at a proxy cluster, inbound peers authenticate via their WireGuard tunnel identity (no OIDC), and an ACL policy is auto-generated from access_groups to the cluster's proxy-peer group. Requires mode=http.
Default:false
proxy_clusterstringoptional
The proxy cluster handling this service (derived from domain)
rewrite_redirectsbooleanoptional
When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
targetsarray<object>required
List of target backends for this service
terminatedbooleanoptional
Whether the service has been terminated. Terminated services cannot be updated. Services that violate the Terms of Service will be terminated.
400Bad Request
401Requires authentication
403Forbidden
404Resource not found
500Internal Server Error

Error handling

A 400 is returned: Bad Request. A 401 is returned: Requires authentication. A 403 is returned: Forbidden. A 404 is returned: Resource not found. A 500 is returned: Internal Server Error.