NetBird Full API Reference + Read-Only MCP Prototype
PUT/api/reverse-proxies/services/{serviceId}

Replace a reverse proxy service

Replaces the configuration of an existing reverse proxy service. Supply name, domain, and enabled, and include the service settings and targets you want applied. A 200 response returns the updated service object.

1 parameter · 12 body fields
serviceIdstringrequired
The unique identifier of the service to replace.

JSON configuration for the service. Supply name, domain, and enabled; the remaining fields configure access, routing, and backend targets.

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.
authobjectoptional
Authentication configuration for the service, including bearer, header, link, password, or PIN authentication.
domainstringrequired
Domain for the service
enabledbooleanrequired
Whether the service is enabled
Default:true
listen_portintegeroptional
Port the proxy listens on (L4/TLS only). Set to 0 for auto-assignment.
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
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
rewrite_redirectsbooleanoptional
When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
targetsarray<object>optional
List of target backends for this service

7 status codes
200Returns the updated service object, including its identifier, name, domain, targets, enabled status, authentication configuration, and metadata.
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.
400Returned when the request is invalid or a service field fails validation.
401Returned when the request lacks authentication.
403Returned when the authenticated user is forbidden from updating the service.
404Returned when the service is not found.
409Returned when updating the service conflicts with an existing resource or configuration.
messagestringoptional
A human-readable error message.
500Returned when an internal server error occurs.

Error handling

A 400 is returned when the request is invalid; a 401 indicates missing authentication, a 403 indicates forbidden access, a 404 indicates that the service was not found, a 409 indicates a conflict, and a 500 indicates an internal server error. name, domain, and enabled are required; mode must be http, tcp, udp, or tls, and target protocol, target_type, and port values must satisfy their declared schema constraints. The serviceId path parameter must identify the service to replace.