Create a Route

POST /apisix/admin/routes

Create a Route

Create a new route with an auto-generated ID.

A route must include at least a uri and one of: upstream (inline), upstream_id, service_id, or plugins.

Parameters

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

Request body

Route 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 route.
• desc (string, optional): Description of what this route does.
• 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.
• uri (string, optional): URI path pattern to match. Supports exact match (/api/v1/users) and prefix match (/api/*). Mutually exclusive with uris.
• uris (array, optional): Multiple URI patterns. Mutually exclusive with uri.
• host (string, optional): Single hostname to match against the request's Host header. Supports wildcard prefix (*.example.com). Mutually exclusive with hosts.
• hosts (array, optional): Multiple hostnames to match. Mutually exclusive with host.
• methods (array, optional): HTTP methods allowed on this route. If empty or not set, all methods are allowed.
• remote_addr (string, optional): Single client IP address or CIDR range to match. Mutually exclusive with remote_addrs.
• remote_addrs (array, optional): Multiple client IP addresses or CIDR ranges to match. Mutually exclusive with remote_addr.
• priority (integer, optional): Route priority. When multiple routes match the same request, the one with the highest priority wins.
• vars (array, optional): Custom matching conditions using APISIX expressions. Each condition is an array of [variable, operator, value].
• filter_func (string, optional): Custom Lua function for advanced request matching. Must start with function.
• 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.

• plugin_config_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 (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
• 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.
• enable_websocket (boolean, optional): Enable WebSocket proxying on this route.
• status (integer, optional): Route status.
• script (string, optional): Lua script for plugin orchestration. Cannot be used together with plugins or plugin_config_id.
• script_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
• anyOf variant 1: Plugin and URI required
• anyOf variant 2: Upstream and URI required
• anyOf variant 3: Upstream ID and URI required
• anyOf variant 4: Service ID and URI required
• anyOf variant 5: Plugin and URIs required
• anyOf variant 6: Upstream and URIs required
• anyOf variant 7: Upstream ID and URIs required
• anyOf variant 8: Service ID and URIs required
• anyOf variant 9: Script and URI required
• anyOf variant 10: Script and URIs required

Responses

• 201: Created
• key (string, required):
• value (object, required): Route configuration. A route matches incoming requests by URI, host, methods, and other conditions, then forwards them to an upstream.

A route must have at least a uri (or uris) and one of: upstream, upstream_id, service_id, or plugins.

• 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 route.
• value.desc (string, optional): Description of what this route does.
• 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.uri (string, optional): URI path pattern to match. Supports exact match (/api/v1/users) and prefix match (/api/*). Mutually exclusive with uris.
• value.uris (array, optional): Multiple URI patterns. Mutually exclusive with uri.
• value.host (string, optional): Single hostname to match against the request's Host header. Supports wildcard prefix (*.example.com). Mutually exclusive with hosts.
• value.hosts (array, optional): Multiple hostnames to match. Mutually exclusive with host.
• value.methods (array, optional): HTTP methods allowed on this route. If empty or not set, all methods are allowed.
• value.remote_addr (string, optional): Single client IP address or CIDR range to match. Mutually exclusive with remote_addrs.
• value.remote_addrs (array, optional): Multiple client IP addresses or CIDR ranges to match. Mutually exclusive with remote_addr.
• value.priority (integer, optional): Route priority. When multiple routes match the same request, the one with the highest priority wins.
• value.vars (array, optional): Custom matching conditions using APISIX expressions. Each condition is an array of [variable, operator, value].
• value.filter_func (string, optional): Custom Lua function for advanced request matching. Must start with function.
• 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.

• value.plugin_config_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 (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.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.enable_websocket (boolean, optional): Enable WebSocket proxying on this route.
• value.status (integer, optional): Route status.
• value.script (string, optional): Lua script for plugin orchestration. Cannot be used together with plugins or plugin_config_id.
• value.script_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
• anyOf variant 1: Plugin and URI required
• anyOf variant 2: Upstream and URI required
• anyOf variant 3: Upstream ID and URI required
• anyOf variant 4: Service ID and URI required
• anyOf variant 5: Plugin and URIs required
• anyOf variant 6: Upstream and URIs required
• anyOf variant 7: Upstream ID and URIs required
• anyOf variant 8: Service ID and URIs required
• anyOf variant 9: Script and URI required
• anyOf variant 10: Script and URIs required
• 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 -i http://127.0.0.1:9180/apisix/admin/routes \
  -H 'X-API-KEY: your-api-key' \
  -H 'Content-Type: application/json' \
  -X POST -d '{
    "uri": "/api/v1/users/*",
    "upstream": {
      "type": "roundrobin",
      "nodes": {"10.0.0.1:8080": 1}
    }
  }'