---
title: "Add a server to a stream upstream server group"
method: POST
path: "/stream/upstreams/{streamUpstreamName}/servers/"
tags: ["Stream Upstreams", "Method POST"]
---

# Add a server to a stream upstream server group

`POST /stream/upstreams/{streamUpstreamName}/servers/`

Adds a new server to a stream upstream server group. Server parameters are specified in the JSON format.

## Request body

- NginxStreamUpstreamConfServer — Dynamically configurable parameters of a stream upstream <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</a>:
  - `id` integer — The ID of the stream upstream server. The ID is assigned automatically and cannot be changed.
  - `server` string — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</a> parameter of the stream upstream server. When adding a server, it is possible to specify it as a domain name. In this case, changes of the IP addresses that correspond to a domain name will be monitored and automatically applied to the upstream configuration without the need of restarting nginx. This requires the <a href="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#resolver">resolver</a> directive in the “<code>stream</code>” block. See also the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#resolve">resolve</a> parameter of the stream upstream server.
  - `service` string — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</a> parameter of the stream upstream server. This parameter cannot be changed.
  - `weight` integer — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">weight</a> parameter of the stream upstream server.
  - `max_conns` integer — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns">max_conns</a> parameter of the stream upstream server.
  - `max_fails` integer — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_fails">max_fails</a> parameter of the stream upstream server.
  - `fail_timeout` string — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#fail_timeout">fail_timeout</a> parameter of the stream upstream server.
  - `slow_start` string — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#slow_start">slow_start</a> parameter of the stream upstream server.
  - `backup` boolean — When <code>true</code>, adds a <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#backup">backup</a> server. This parameter cannot be changed.
  - `down` boolean — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#down">down</a> parameter of the stream upstream server.
  - `parent` string — Parent server ID of the resolved server. The ID is assigned automatically and cannot be changed.
  - `host` string — Hostname of the resolved server. The hostname is assigned automatically and cannot be changed.

## Response `201`

Created

- NginxStreamUpstreamConfServer — Dynamically configurable parameters of a stream upstream <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</a>:
  - `id` integer — The ID of the stream upstream server. The ID is assigned automatically and cannot be changed.
  - `server` string — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</a> parameter of the stream upstream server. When adding a server, it is possible to specify it as a domain name. In this case, changes of the IP addresses that correspond to a domain name will be monitored and automatically applied to the upstream configuration without the need of restarting nginx. This requires the <a href="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#resolver">resolver</a> directive in the “<code>stream</code>” block. See also the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#resolve">resolve</a> parameter of the stream upstream server.
  - `service` string — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</a> parameter of the stream upstream server. This parameter cannot be changed.
  - `weight` integer — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">weight</a> parameter of the stream upstream server.
  - `max_conns` integer — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns">max_conns</a> parameter of the stream upstream server.
  - `max_fails` integer — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_fails">max_fails</a> parameter of the stream upstream server.
  - `fail_timeout` string — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#fail_timeout">fail_timeout</a> parameter of the stream upstream server.
  - `slow_start` string — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#slow_start">slow_start</a> parameter of the stream upstream server.
  - `backup` boolean — When <code>true</code>, adds a <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#backup">backup</a> server. This parameter cannot be changed.
  - `down` boolean — Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#down">down</a> parameter of the stream upstream server.
  - `parent` string — Parent server ID of the resolved server. The ID is assigned automatically and cannot be changed.
  - `host` string — Hostname of the resolved server. The hostname is assigned automatically and cannot be changed.

## Other responses

- `400` — Upstream is static (*UpstreamStatic*), invalid “**parameter**” value (*UpstreamConfFormatError*), missing “*server*” argument (*UpstreamConfFormatError*), unknown parameter “**name**” (*UpstreamConfFormatError*), nested object or list (*UpstreamConfFormatError*), “*error*” while parsing (*UpstreamBadAddress*), no port in server “*host*” (*UpstreamBadAddress*), service upstream “*host*” may not have port (*UpstreamBadAddress*), service upstream “*host*” requires domain name (*UpstreamBadAddress*), invalid “*weight*” (*UpstreamBadWeight*), invalid “*max_conns*” (*UpstreamBadMaxConns*), invalid “*max_fails*” (*UpstreamBadMaxFails*), invalid “*fail_timeout*” (*UpstreamBadFailTimeout*), invalid “*slow_start*” (*UpstreamBadSlowStart*), “*service*” is empty (*UpstreamBadService*), no resolver defined to resolve (*UpstreamConfNoResolver*), upstream “**name**” has no backup (*UpstreamNoBackup*), upstream “**name**” memory exhausted (*UpstreamOutOfMemory*), reading request body failed *BodyReadError*)
- `404` — Unknown version (*UnknownVersion*), upstream not found (*UpstreamNotFound*)
- `405` — Method disabled (*MethodDisabled*)
- `409` — Entry exists (*EntryExists*)
- `415` — JSON error (*JsonError*)

---

[API](https://skmtc.dev/nginx/apis/nginx-plus-rest-api.md) · [All operations](https://skmtc.dev/nginx/apis/nginx-plus-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nginx/nginx-plus-rest-api/revisions/533ae7834228/schema)