v11

latestOpenAPI 3.1.0Apache 2.0raw.githubusercontent.com2026-07-065662751.8 MB

Upstreams

Create a new Upstream

post/{workspace}/upstreams

Path parameters

workspacestring required

Example:team-payments

The name of the workspace

Request body

algorithm'consistent-hashing' | 'latency' | 'least-connections' | 'round-robin' | 'sticky-sessions' nullable

Which load balancing algorithm to use.

created_atinteger nullable

Unix epoch when the resource was created.

What to use as hashing input if the primary hash_on does not return a hash (eg. header is missing, or no Consumer identified). Not available if hash_on is set to cookie.

hash_fallback_headerstring nullable

The header name to take the value from as hash input. Only required when hash_fallback is set to header.

hash_fallback_query_argstring nullable

The name of the query string argument to take the value from as hash input. Only required when hash_fallback is set to query_arg.

hash_fallback_uri_capturestring nullable

The name of the route URI capture to take the value from as hash input. Only required when hash_fallback is set to uri_capture.

What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing.

hash_on_cookiestring nullable

The cookie name to take the value from as hash input. Only required when hash_on or hash_fallback is set to cookie. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response.

hash_on_cookie_pathstring nullable

The cookie path to set in the response headers. Only required when hash_on or hash_fallback is set to cookie.

hash_on_headerstring nullable

The header name to take the value from as hash input. Only required when hash_on is set to header.

hash_on_query_argstring nullable

The name of the query string argument to take the value from as hash input. Only required when hash_on is set to query_arg.

hash_on_uri_capturestring nullable

The name of the route URI capture to take the value from as hash input. Only required when hash_on is set to uri_capture.

host_headerstring nullable

The hostname to be used as Host header when proxying requests through Kong.

idstring nullable

A string representing a UUID (universally unique identifier).

namestring required

This is a hostname, which must be equal to the host of a Service.

slotsinteger nullable

The number of slots in the load balancer algorithm. If algorithm is set to round-robin, this setting determines the maximum number of slots. If algorithm is set to consistent-hashing, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range 10-65536.

sticky_sessions_cookiestring nullable

The cookie name to keep sticky sessions.

sticky_sessions_cookie_pathstring nullable

A string representing a URL path, such as /path/to/resource. Must start with a forward slash (/) and must not contain empty segments (i.e., two consecutive forward slashes).

tagsstring[] nullable

An optional set of strings associated with the Upstream for grouping and filtering.

updated_atinteger nullable

Unix epoch when the resource was last updated.

use_srv_nameboolean nullable

If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream Host.

Example request

{
  "algorithm": "round-robin",
  "hash_fallback": "none",
  "hash_on": "none",
  "hash_on_cookie_path": "/",
  "healthchecks": {
    "active": {
      "concurrency": 10,
      "healthy": {
        "http_statuses": [
          200,
          302
        ],
        "interval": 0,
        "successes": 0
      },
      "http_path": "/",
      "https_verify_certificate": true,
      "timeout": 1,
      "type": "http",
      "unhealthy": {
        "http_failures": 0,
        "http_statuses": [
          429,
          404,
          500,
          501,
          502,
          503,
          504,
          505
        ],
        "interval": 0,
        "tcp_failures": 0,
        "timeouts": 0
      }
    },
    "passive": {
      "healthy": {
        "http_statuses": [
          200,
          201,
          202,
          203,
          204,
          205,
          206,
          207,
          208,
          226,
          300,
          301,
          302,
          303,
          304,
          305,
          306,
          307,
          308
        ],
        "successes": 0
      },
      "type": "http",
      "unhealthy": {
        "http_failures": 0,
        "http_statuses": [
          429,
          500,
          503
        ],
        "tcp_failures": 0,
        "timeouts": 0
      }
    },
    "threshold": 0
  },
  "id": "6eed5e9c-5398-4026-9a4c-d48f18a2431e",
  "name": "api.example.internal",
  "slots": 10000
}

Response

Successfully created Upstream