API7 Docs

Create or Replace an Upstream

PUT /apisix/admin/upstreams/{id}

PUT /apisix/admin/upstreams/{id}

Interactive request editor loads with JavaScript.

Authorization

X-API-KEY<token>

Admin API key configured in config.yaml under deployment.admin.admin_key. You can also pass the key as a query parameter api_key or cookie x_api_key.

In: header

Path Parameters

id*string

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Query Parameters

ttl?integer

Time-to-live in seconds. The resource is automatically removed when it expires.

Range1 <= value

Request Body

application/json

Upstream configuration body for create / replace / patch.

Upstream configuration defining backend service nodes and load balancing behavior.

An upstream must specify either nodes (static list) or service_name + discovery_type (service discovery).

Upstream configuration defining backend service nodes and load balancing behavior.

An upstream must specify either nodes (static list) or service_name + discovery_type (service discovery).

Response Body

application/json

application/json

application/json

curl -X PUT "http://127.0.0.1:9180/apisix/admin/upstreams/my-resource-1?ttl=3600" \  -H "Content-Type: application/json" \  -d '{    "name": "backend-cluster",    "desc": "Primary backend service cluster",    "type": "roundrobin",    "nodes": {      "10.0.0.1:8080": 3,      "10.0.0.2:8080": 2,      "10.0.0.3:8080": 1    },    "retries": 3,    "retry_timeout": 5,    "timeout": {      "connect": 6,      "send": 6,      "read": 6    },    "checks": {      "active": {        "type": "http",        "http_path": "/health",        "healthy": {          "interval": 5,          "successes": 2        },        "unhealthy": {          "interval": 3,          "http_failures": 3,          "tcp_failures": 2        }      }    },    "scheme": "http",    "pass_host": "pass"  }'

Created

{
  "key": "/apisix/upstreams/1",
  "value": {
    "timeout": {
      "send": 15,
      "read": 15,
      "connect": 15
    },
    "desc": "desc",
    "id": "1",
    "create_time": 1684290697,
    "retries": 1,
    "pass_host": "pass",
    "update_time": 1684290697,
    "type": "roundrobin",
    "name": "upstream-for-test",
    "hash_on": "vars",
    "nodes": {
      "127.0.0.1:1980": 1
    },
    "scheme": "http"
  }
}
{
  "key": "/apisix/upstreams/1",
  "value": {
    "timeout": {
      "send": 15,
      "read": 15,
      "connect": 15
    },
    "desc": "desc",
    "id": "1",
    "create_time": 1684290697,
    "retries": 1,
    "pass_host": "pass",
    "update_time": 1684291419,
    "type": "roundrobin",
    "name": "upstream-for-test",
    "hash_on": "vars",
    "nodes": {
      "httpbin.org:443": 1
    },
    "scheme": "https"
  }
}
{
  "key": "/apisix/upstreams/1",
  "value": {
    "hash_on": "vars",
    "desc": "desc",
    "id": "1",
    "create_time": 1684292372,
    "checks": {
      "passive": {
        "type": "http",
        "healthy": {
          "http_statuses": [
            200,
            201
          ],
          "successes": 3
        },
        "unhealthy": {
          "timeouts": 7,
          "http_statuses": [
            500
          ],
          "http_failures": 3,
          "tcp_failures": 3
        }
      },
      "active": {
        "host": "foo.com",
        "concurrency": 10,
        "http_path": "/status",
        "https_verify_certificate": true,
        "type": "http",
        "req_headers": [
          "User-Agent: curl/7.29.0"
        ],
        "healthy": {
          "successes": 1,
          "http_statuses": [
            200,
            302
          ],
          "interval": 2
        },
        "timeout": 5,
        "unhealthy": {
          "timeouts": 3,
          "http_statuses": [
            429,
            404,
            500,
            501,
            502,
            503,
            504,
            505
          ],
          "interval": 1,
          "http_failures": 2,
          "tcp_failures": 2
        }
      }
    },
    "pass_host": "pass",
    "update_time": 1684292372,
    "type": "roundrobin",
    "name": "upstream-for-test",
    "retries": 1,
    "nodes": {
      "127.0.0.1:1980": 1,
      "127.0.0.1:1970": 1
    },
    "scheme": "http"
  }
}
Complete operation details and schema variants

PUT /apisix/admin/upstreams/{id}

Create or Replace an Upstream

Create a new upstream with a specified ID, or fully replace an existing upstream.

Parameters

  • id (path, string, required): Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.
  • ttl (query, integer, optional): Time-to-live in seconds. The resource is automatically removed when it expires.

Request body

Upstream configuration body for create / replace / patch.

Content type: application/json

  • id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
  • anyOf variant 1: String ID
  • anyOf variant 2: Integer ID
  • name (string, optional): Human-readable name for the upstream.
  • desc (string, optional): Description of the upstream.
  • labels (object, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
  • create_time (integer, optional): Unix timestamp when the upstream was created. Read-only, set automatically.
  • update_time (integer, optional): Unix timestamp when the upstream was last updated. Read-only, set automatically.
  • nodes (object, optional): The upstream endpoints.
  • allOf variant 1
  • anyOf variant 1: Weight Mapping
  • anyOf variant 2: Node Objects
  • nodes[].host (string, required): Hostname or IP address of the upstream node.
  • nodes[].port (integer, optional): Port of the upstream node.
  • nodes[].weight (integer, required): Weight for load balancing. Higher values mean more traffic. 0 means no traffic.
  • nodes[].priority (integer, optional): Priority of the node. Nodes with higher priority are used first. Lower-priority nodes serve as fallbacks.
  • nodes[].metadata (object, optional): Arbitrary metadata associated with this node.
  • retries (integer, optional): Number of retry attempts when a request to the upstream fails.
  • retry_timeout (number, optional): Maximum time in seconds for retry attempts. 0 disables the retry timeout.
  • timeout (object, optional): Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.
  • timeout.connect (number, required): Timeout in seconds for establishing a connection to the upstream.
  • timeout.send (number, required): Timeout in seconds for sending data to the upstream.
  • timeout.read (number, required): Timeout in seconds for reading the response from the upstream.
  • type (string, optional): Load balancing algorithm.
  • hash_on (string, optional): What to hash on when type is chash.
  • key (string, optional): The hash key used when type is chash. Required when hash_on is header, cookie, vars, or vars_combinations. Not needed when hash_on is consumer.
  • scheme (string, optional): Protocol for communicating with upstream nodes.
  • checks (object, optional): Health check configuration for monitoring upstream node availability. Active checks require at least the active field.
  • checks.active (object, optional): Active health check configuration. APISIX periodically sends probes to upstream nodes to determine their health status.
  • checks.active.type (string, optional): Protocol type for health check probes.
  • checks.active.timeout (number, optional): Timeout in seconds for each health check probe.
  • checks.active.concurrency (integer, optional): Number of targets to check concurrently during active health checks.
  • checks.active.host (string, optional): Hostname to use in the health check probe Host header. Defaults to the upstream node's host.
  • checks.active.port (integer, optional): Port to use for health check probes. Defaults to the upstream node's port.
  • checks.active.http_path (string, optional): HTTP request path for health check probes.
  • checks.active.https_verify_certificate (boolean, optional): Whether to verify the upstream's TLS certificate during HTTPS health checks.
  • checks.active.req_headers (array, optional): Additional HTTP headers to include in health check probe requests.
  • checks.active.healthy (object, optional): Thresholds for considering a target healthy during active checks.
  • checks.active.healthy.interval (integer, optional): Interval in seconds between active health check probes for healthy targets.
  • checks.active.healthy.http_statuses (array, optional): HTTP status codes that indicate a healthy target.
  • checks.active.healthy.successes (integer, optional): Number of consecutive successful probes to consider a target healthy.
  • checks.active.unhealthy (object, optional): Thresholds for considering a target unhealthy during active checks.
  • checks.active.unhealthy.interval (integer, optional): Interval in seconds between active health check probes for unhealthy targets.
  • checks.active.unhealthy.http_statuses (array, optional): HTTP status codes that indicate an unhealthy target.
  • checks.active.unhealthy.http_failures (integer, optional): Number of HTTP failures to consider a target unhealthy.
  • checks.active.unhealthy.tcp_failures (integer, optional): Number of TCP connection failures to consider a target unhealthy.
  • checks.active.unhealthy.timeouts (integer, optional): Number of probe timeouts to consider a target unhealthy.
  • checks.passive (object, optional): Passive health check configuration. APISIX monitors real traffic responses to determine upstream node health — no extra probes are sent.
  • checks.passive.type (string, optional): Protocol type for passive health monitoring.
  • checks.passive.healthy (object, optional): Thresholds for considering a target healthy based on real traffic responses.
  • checks.passive.healthy.http_statuses (array, optional): HTTP status codes from real traffic that indicate a healthy target.
  • checks.passive.healthy.successes (integer, optional): Number of consecutive successful requests to restore a target to healthy status.
  • checks.passive.unhealthy (object, optional): Thresholds for considering a target unhealthy based on real traffic responses.
  • checks.passive.unhealthy.http_statuses (array, optional): HTTP status codes from real traffic that indicate an unhealthy target.
  • checks.passive.unhealthy.tcp_failures (integer, optional): Number of TCP failures from real traffic to consider a target unhealthy.
  • checks.passive.unhealthy.timeouts (integer, optional): Number of timeouts from real traffic to consider a target unhealthy.
  • checks.passive.unhealthy.http_failures (integer, optional): Number of HTTP failures from real traffic to consider a target unhealthy.
  • anyOf variant 1: Active Check
  • anyOf variant 2: Passive Check
  • tls (object, optional): TLS configuration for connecting to upstream nodes over HTTPS/gRPCS.
  • tls.client_cert_id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
  • anyOf variant 1: String ID
  • anyOf variant 2: Integer ID
  • tls.client_cert (string, optional): PEM-encoded client certificate for mTLS with the upstream.
  • tls.client_key (string, optional): PEM-encoded client private key for mTLS with the upstream.
  • tls.verify (boolean, optional): Whether to verify the upstream server's TLS certificate. Currently only supported for Kafka upstreams.
  • keepalive_pool (object, optional): Connection pool configuration for keepalive connections to upstream nodes.
  • keepalive_pool.size (integer, optional): Maximum number of keepalive connections cached in the connection pool.
  • keepalive_pool.idle_timeout (number, optional): Time in seconds after which an idle keepalive connection is closed. 0 disables the timeout.
  • keepalive_pool.requests (integer, optional): Maximum number of requests that can be sent over a single keepalive connection before it is closed.
  • pass_host (string, optional): How to set the Host header when proxying to the upstream.
  • upstream_host (string, optional): Custom Host header value. Only effective when pass_host is rewrite.
  • discovery_type (string, optional): Service discovery type (e.g., dns, consul, nacos, eureka). Required when using service discovery instead of static nodes.
  • discovery_args (object, optional): Additional arguments for service discovery.
  • discovery_args.namespace_id (string, optional): Namespace ID for Nacos service discovery.
  • discovery_args.group_name (string, optional): Group name for service discovery.
  • service_name (string, optional): Service name for service discovery. Required when discovery_type is set.
  • oneOf variant 1: Use Upstream Nodes
  • oneOf variant 2: Use Service Registry

Responses

  • 201: Created
  • key (string, required):
  • value (object, required): Upstream configuration defining backend service nodes and load balancing behavior.

An upstream must specify either nodes (static list) or service_name + discovery_type (service discovery).

  • value.id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
  • anyOf variant 1: String ID
  • anyOf variant 2: Integer ID
  • value.name (string, optional): Human-readable name for the upstream.
  • value.desc (string, optional): Description of the upstream.
  • value.labels (object, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
  • value.create_time (integer, optional): Unix timestamp when the upstream was created. Read-only, set automatically.
  • value.update_time (integer, optional): Unix timestamp when the upstream was last updated. Read-only, set automatically.
  • value.nodes (object, optional): The upstream endpoints.
  • allOf variant 1
  • anyOf variant 1: Weight Mapping
  • anyOf variant 2: Node Objects
  • value.nodes[].host (string, required): Hostname or IP address of the upstream node.
  • value.nodes[].port (integer, optional): Port of the upstream node.
  • value.nodes[].weight (integer, required): Weight for load balancing. Higher values mean more traffic. 0 means no traffic.
  • value.nodes[].priority (integer, optional): Priority of the node. Nodes with higher priority are used first. Lower-priority nodes serve as fallbacks.
  • value.nodes[].metadata (object, optional): Arbitrary metadata associated with this node.
  • value.retries (integer, optional): Number of retry attempts when a request to the upstream fails.
  • value.retry_timeout (number, optional): Maximum time in seconds for retry attempts. 0 disables the retry timeout.
  • value.timeout (object, optional): Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.
  • value.timeout.connect (number, required): Timeout in seconds for establishing a connection to the upstream.
  • value.timeout.send (number, required): Timeout in seconds for sending data to the upstream.
  • value.timeout.read (number, required): Timeout in seconds for reading the response from the upstream.
  • value.type (string, optional): Load balancing algorithm.
  • value.hash_on (string, optional): What to hash on when type is chash.
  • value.key (string, optional): The hash key used when type is chash. Required when hash_on is header, cookie, vars, or vars_combinations. Not needed when hash_on is consumer.
  • value.scheme (string, optional): Protocol for communicating with upstream nodes.
  • value.checks (object, optional): Health check configuration for monitoring upstream node availability. Active checks require at least the active field.
  • value.checks.active (object, optional): Active health check configuration. APISIX periodically sends probes to upstream nodes to determine their health status.
  • value.checks.active.type (string, optional): Protocol type for health check probes.
  • value.checks.active.timeout (number, optional): Timeout in seconds for each health check probe.
  • value.checks.active.concurrency (integer, optional): Number of targets to check concurrently during active health checks.
  • value.checks.active.host (string, optional): Hostname to use in the health check probe Host header. Defaults to the upstream node's host.
  • value.checks.active.port (integer, optional): Port to use for health check probes. Defaults to the upstream node's port.
  • value.checks.active.http_path (string, optional): HTTP request path for health check probes.
  • value.checks.active.https_verify_certificate (boolean, optional): Whether to verify the upstream's TLS certificate during HTTPS health checks.
  • value.checks.active.req_headers (array, optional): Additional HTTP headers to include in health check probe requests.
  • value.checks.active.healthy (object, optional): Thresholds for considering a target healthy during active checks.
  • value.checks.active.healthy.interval (integer, optional): Interval in seconds between active health check probes for healthy targets.
  • value.checks.active.healthy.http_statuses (array, optional): HTTP status codes that indicate a healthy target.
  • value.checks.active.healthy.successes (integer, optional): Number of consecutive successful probes to consider a target healthy.
  • value.checks.active.unhealthy (object, optional): Thresholds for considering a target unhealthy during active checks.
  • value.checks.active.unhealthy.interval (integer, optional): Interval in seconds between active health check probes for unhealthy targets.
  • value.checks.active.unhealthy.http_statuses (array, optional): HTTP status codes that indicate an unhealthy target.
  • value.checks.active.unhealthy.http_failures (integer, optional): Number of HTTP failures to consider a target unhealthy.
  • value.checks.active.unhealthy.tcp_failures (integer, optional): Number of TCP connection failures to consider a target unhealthy.
  • value.checks.active.unhealthy.timeouts (integer, optional): Number of probe timeouts to consider a target unhealthy.
  • value.checks.passive (object, optional): Passive health check configuration. APISIX monitors real traffic responses to determine upstream node health — no extra probes are sent.
  • value.checks.passive.type (string, optional): Protocol type for passive health monitoring.
  • value.checks.passive.healthy (object, optional): Thresholds for considering a target healthy based on real traffic responses.
  • value.checks.passive.healthy.http_statuses (array, optional): HTTP status codes from real traffic that indicate a healthy target.
  • value.checks.passive.healthy.successes (integer, optional): Number of consecutive successful requests to restore a target to healthy status.
  • value.checks.passive.unhealthy (object, optional): Thresholds for considering a target unhealthy based on real traffic responses.
  • value.checks.passive.unhealthy.http_statuses (array, optional): HTTP status codes from real traffic that indicate an unhealthy target.
  • value.checks.passive.unhealthy.tcp_failures (integer, optional): Number of TCP failures from real traffic to consider a target unhealthy.
  • value.checks.passive.unhealthy.timeouts (integer, optional): Number of timeouts from real traffic to consider a target unhealthy.
  • value.checks.passive.unhealthy.http_failures (integer, optional): Number of HTTP failures from real traffic to consider a target unhealthy.
  • anyOf variant 1: Active Check
  • anyOf variant 2: Passive Check
  • value.tls (object, optional): TLS configuration for connecting to upstream nodes over HTTPS/gRPCS.
  • value.tls.client_cert_id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
  • anyOf variant 1: String ID
  • anyOf variant 2: Integer ID
  • value.tls.client_cert (string, optional): PEM-encoded client certificate for mTLS with the upstream.
  • value.tls.client_key (string, optional): PEM-encoded client private key for mTLS with the upstream.
  • value.tls.verify (boolean, optional): Whether to verify the upstream server's TLS certificate. Currently only supported for Kafka upstreams.
  • value.keepalive_pool (object, optional): Connection pool configuration for keepalive connections to upstream nodes.
  • value.keepalive_pool.size (integer, optional): Maximum number of keepalive connections cached in the connection pool.
  • value.keepalive_pool.idle_timeout (number, optional): Time in seconds after which an idle keepalive connection is closed. 0 disables the timeout.
  • value.keepalive_pool.requests (integer, optional): Maximum number of requests that can be sent over a single keepalive connection before it is closed.
  • value.pass_host (string, optional): How to set the Host header when proxying to the upstream.
  • value.upstream_host (string, optional): Custom Host header value. Only effective when pass_host is rewrite.
  • value.discovery_type (string, optional): Service discovery type (e.g., dns, consul, nacos, eureka). Required when using service discovery instead of static nodes.
  • value.discovery_args (object, optional): Additional arguments for service discovery.
  • value.discovery_args.namespace_id (string, optional): Namespace ID for Nacos service discovery.
  • value.discovery_args.group_name (string, optional): Group name for service discovery.
  • value.service_name (string, optional): Service name for service discovery. Required when discovery_type is set.
  • oneOf variant 1: Use Upstream Nodes
  • oneOf variant 2: Use Service Registry
  • createdIndex (integer, optional):
  • modifiedIndex (integer, optional):
  • 400: Bad Request — The request body is invalid or missing required fields.
  • error_msg (string, required): Human-readable error message describing what went wrong.
  • 401: Unauthorized — The API key is missing, invalid, or lacks permission.
  • error_msg (string, required): Authentication error message.
  • description (string, optional): Detailed reason for the authentication failure.

cURL

curl -X PUT 'http://127.0.0.1:9180/apisix/admin/upstreams/{id}'

Create an Upstream

Previous Page

Update an Upstream (Partial)

Next Page