Kong · Schema
Upstream
The upstream object represents a virtual hostname and can be used to loadbalance incoming requests over multiple services (targets). So for example an upstream named `service.v1.xyz` for a Service object whose `host` is `service.v1.xyz`. Requests for this Service would be proxied to the targets defined within the upstream. An upstream also includes a [health checker][healthchecks], which is able to enable and disable targets based on their ability or inability to serve requests. The configuration for the health checker is stored in the upstream object, and applies to all of its targets.
API GatewayAI GatewayAI ConnectivityAgent GatewayEvent GatewayMCP RegistryService MeshLLMKafkaKonnectOpen-Source
Properties
| Name | Type | Description |
|---|---|---|
| algorithm | string | Which load balancing algorithm to use. |
| client_certificate | object | If set, the certificate to be used as client certificate while TLS handshaking to the upstream server. |
| created_at | integer | Unix epoch when the resource was created. |
| hash_fallback | string | 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_header | string | The header name to take the value from as hash input. Only required when `hash_fallback` is set to `header`. |
| hash_fallback_query_arg | string | 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_capture | string | 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`. |
| hash_on | string | What to use as hashing input. Using `none` results in a weighted-round-robin scheme with no hashing. |
| hash_on_cookie | string | 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 |
| hash_on_cookie_path | string | The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`. |
| hash_on_header | string | The header name to take the value from as hash input. Only required when `hash_on` is set to `header`. |
| hash_on_query_arg | string | 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_capture | string | 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`. |
| healthchecks | object | The array of healthchecks. |
| host_header | string | The hostname to be used as `Host` header when proxying requests through Kong. |
| id | string | A string representing a UUID (universally unique identifier). |
| name | string | This is a hostname, which must be equal to the `host` of a Service. |
| slots | integer | 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 set |
| sticky_sessions_cookie | string | The cookie name to keep sticky sessions. |
| sticky_sessions_cookie_path | string | 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). |
| tags | array | An optional set of strings associated with the Upstream for grouping and filtering. |
| updated_at | integer | Unix epoch when the resource was last updated. |
| use_srv_name | boolean | If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream `Host`. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "#/components/schemas/Upstream",
"title": "Upstream",
"x-speakeasy-entity": "Upstream",
"description": "The upstream object represents a virtual hostname and can be used to loadbalance incoming requests over multiple services (targets). So for example an upstream named `service.v1.xyz` for a Service object whose `host` is `service.v1.xyz`. Requests for this Service would be proxied to the targets defined within the upstream. An upstream also includes a [health checker][healthchecks], which is able to enable and disable targets based on their ability or inability to serve requests. The configuration for the health checker is stored in the upstream object, and applies to all of its targets.",
"type": "object",
"properties": {
"algorithm": {
"description": "Which load balancing algorithm to use.",
"type": "string",
"default": "round-robin",
"enum": [
"consistent-hashing",
"latency",
"least-connections",
"round-robin",
"sticky-sessions"
],
"nullable": true
},
"client_certificate": {
"description": "If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.",
"type": "object",
"nullable": true,
"properties": {
"id": {
"type": "string"
}
},
"x-foreign": true
},
"created_at": {
"description": "Unix epoch when the resource was created.",
"type": "integer",
"nullable": true
},
"hash_fallback": {
"description": "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`.",
"type": "string",
"default": "none",
"enum": [
"consumer",
"cookie",
"header",
"ip",
"none",
"path",
"query_arg",
"uri_capture"
],
"nullable": true
},
"hash_fallback_header": {
"description": "The header name to take the value from as hash input. Only required when `hash_fallback` is set to `header`.",
"type": "string",
"nullable": true
},
"hash_fallback_query_arg": {
"description": "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`.",
"type": "string",
"minLength": 1,
"nullable": true
},
"hash_fallback_uri_capture": {
"description": "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`.",
"type": "string",
"minLength": 1,
"nullable": true
},
"hash_on": {
"description": "What to use as hashing input. Using `none` results in a weighted-round-robin scheme with no hashing.",
"type": "string",
"default": "none",
"enum": [
"consumer",
"cookie",
"header",
"ip",
"none",
"path",
"query_arg",
"uri_capture"
],
"nullable": true
},
"hash_on_cookie": {
"description": "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.",
"type": "string",
"nullable": true
},
"hash_on_cookie_path": {
"description": "The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`.",
"type": "string",
"default": "/",
"nullable": true
},
"hash_on_header": {
"description": "The header name to take the value from as hash input. Only required when `hash_on` is set to `header`.",
"type": "string",
"nullable": true
},
"hash_on_query_arg": {
"description": "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`.",
"type": "string",
"minLength": 1,
"nullable": true
},
"hash_on_uri_capture": {
"description": "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`.",
"type": "string",
"minLength": 1,
"nullable": true
},
"healthchecks": {
"description": "The array of healthchecks.",
"type": "object",
"default": {
"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
}
}
},
"nullable": true,
"properties": {
"active": {
"type": "object",
"default": {
"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
}
},
"properties": {
"concurrency": {
"type": "integer",
"default": 10,
"maximum": 2147483648,
"minimum": 1
},
"headers": {
"description": "A map of header names to arrays of header values.",
"type": "object",
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
}
},
"healthy": {
"type": "object",
"default": {
"http_statuses": [
200,
302
],
"interval": 0,
"successes": 0
},
"properties": {
"http_statuses": {
"type": "array",
"items": {
"maximum": 999,
"minimum": 100,
"type": "integer"
},
"default": [
200,
302
]
},
"interval": {
"type": "number",
"default": 0,
"maximum": 65535,
"minimum": 0
},
"successes": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
}
}
},
"http_path": {
"description": "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).",
"type": "string",
"default": "/"
},
"https_sni": {
"description": "A string representing an SNI (server name indication) value for TLS.",
"type": "string"
},
"https_verify_certificate": {
"type": "boolean",
"default": true
},
"timeout": {
"type": "number",
"default": 1,
"maximum": 65535,
"minimum": 0
},
"type": {
"type": "string",
"default": "http",
"enum": [
"grpc",
"grpcs",
"http",
"https",
"tcp"
]
},
"unhealthy": {
"type": "object",
"default": {
"http_failures": 0,
"http_statuses": [
429,
404,
500,
501,
502,
503,
504,
505
],
"interval": 0,
"tcp_failures": 0,
"timeouts": 0
},
"properties": {
"http_failures": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
},
"http_statuses": {
"type": "array",
"items": {
"maximum": 999,
"minimum": 100,
"type": "integer"
},
"default": [
429,
404,
500,
501,
502,
503,
504,
505
]
},
"interval": {
"type": "number",
"default": 0,
"maximum": 65535,
"minimum": 0
},
"tcp_failures": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
},
"timeouts": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
}
}
}
}
},
"passive": {
"type": "object",
"default": {
"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
}
},
"properties": {
"healthy": {
"type": "object",
"default": {
"http_statuses": [
200,
201,
202,
203,
204,
205,
206,
207,
208,
226,
300,
301,
302,
303,
304,
305,
306,
307,
308
],
"successes": 0
},
"properties": {
"http_statuses": {
"type": "array",
"items": {
"maximum": 999,
"minimum": 100,
"type": "integer"
},
"default": [
200,
201,
202,
203,
204,
205,
206,
207,
208,
226,
300,
301,
302,
303,
304,
305,
306,
307,
308
]
},
"successes": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
}
}
},
"type": {
"type": "string",
"default": "http",
"enum": [
"grpc",
"grpcs",
"http",
"https",
"tcp"
]
},
"unhealthy": {
"type": "object",
"default": {
"http_failures": 0,
"http_statuses": [
429,
500,
503
],
"tcp_failures": 0,
"timeouts": 0
},
"properties": {
"http_failures": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
},
"http_statuses": {
"type": "array",
"items": {
"maximum": 999,
"minimum": 100,
"type": "integer"
},
"default": [
429,
500,
503
]
},
"tcp_failures": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
},
"timeouts": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
}
}
}
}
},
"threshold": {
"type": "number",
"default": 0,
"maximum": 100,
"minimum": 0
}
}
},
"host_header": {
"description": "The hostname to be used as `Host` header when proxying requests through Kong.",
"type": "string",
"nullable": true
},
"id": {
"description": "A string representing a UUID (universally unique identifier).",
"type": "string",
"nullable": true
},
"name": {
"description": "This is a hostname, which must be equal to the `host` of a Service.",
"type": "string"
},
"slots": {
"description": "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`.",
"type": "integer",
"default": 10000,
"maximum": 65536,
"minimum": 10,
"nullable": true
},
"sticky_sessions_cookie": {
"description": "The cookie name to keep sticky sessions.",
"type": "string",
"nullable": true
},
"sticky_sessions_cookie_path": {
"description": "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).",
"type": "string",
"default": "/",
"nullable": true
},
"tags": {
"description": "An optional set of strings associated with the Upstream for grouping and filtering.",
"type": "array",
"items": {
"description": "A string representing a tag.",
"type": "string"
},
"nullable": true
},
"updated_at": {
"description": "Unix epoch when the resource was last updated.",
"type": "integer",
"nullable": true
},
"use_srv_name": {
"description": "If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream `Host`.",
"type": "boolean",
"default": false,
"nullable": true
}
},
"example": {
"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
},
"additionalProperties": false,
"required": [
"name"
]
}Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/kong-upstream"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.