Create a Stream Route

POST /apisix/admin/stream_routes

Create a Stream Route

Create a new stream route with an auto-generated ID.

Parameters

• ttl (query, integer, optional): Time-to-live in seconds. The resource is automatically removed when it expires.

Request body

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

Example:

{
  "limit-count": {
    "count": 100,
    "time_window": 60
  },
  "key-auth": {}
}

See the Plugin Hub for available plugins and their schemas.

Responses

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

Example:

{
  "limit-count": {
    "count": 100,
    "time_window": 60
  },
  "key-auth": {}
}

See the Plugin Hub for available plugins and their schemas.

• 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 POST 'http://127.0.0.1:9180/apisix/admin/stream_routes'