Envoy · Schema
Envoy Route Configuration
A route configuration specifies how HTTP requests are routed to upstream clusters. It consists of virtual hosts, each containing domain matching rules and ordered route entries that define match criteria and actions.
Cloud-NativeLoad BalancingProxyService Mesh
Properties
| Name | Type | Description |
|---|---|---|
| name | string | Name of the route configuration. |
| virtual_hosts | array | An ordered list of virtual hosts that make up the route table. |
| internal_only_headers | array | Headers that will be stripped from requests coming from external sources. |
| response_headers_to_add | array | Headers to add to all responses. |
| response_headers_to_remove | array | Headers to remove from all responses. |
| request_headers_to_add | array | Headers to add to all requests. |
| request_headers_to_remove | array | Headers to remove from all requests. |
| most_specific_header_mutations_wins | boolean | Whether the most specific header mutation wins when there are conflicts. |
| validate_clusters | boolean | Whether to validate that referenced clusters exist. |
| max_direct_response_body_size_bytes | integer | Maximum size of direct response body. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://www.envoyproxy.io/schemas/route-configuration",
"title": "Envoy Route Configuration",
"description": "A route configuration specifies how HTTP requests are routed to upstream clusters. It consists of virtual hosts, each containing domain matching rules and ordered route entries that define match criteria and actions.",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the route configuration."
},
"virtual_hosts": {
"type": "array",
"description": "An ordered list of virtual hosts that make up the route table.",
"items": {
"$ref": "#/$defs/VirtualHost"
}
},
"internal_only_headers": {
"type": "array",
"description": "Headers that will be stripped from requests coming from external sources.",
"items": {
"type": "string"
}
},
"response_headers_to_add": {
"type": "array",
"description": "Headers to add to all responses.",
"items": {
"$ref": "#/$defs/HeaderValueOption"
}
},
"response_headers_to_remove": {
"type": "array",
"description": "Headers to remove from all responses.",
"items": {
"type": "string"
}
},
"request_headers_to_add": {
"type": "array",
"description": "Headers to add to all requests.",
"items": {
"$ref": "#/$defs/HeaderValueOption"
}
},
"request_headers_to_remove": {
"type": "array",
"description": "Headers to remove from all requests.",
"items": {
"type": "string"
}
},
"most_specific_header_mutations_wins": {
"type": "boolean",
"description": "Whether the most specific header mutation wins when there are conflicts."
},
"validate_clusters": {
"type": "boolean",
"description": "Whether to validate that referenced clusters exist."
},
"max_direct_response_body_size_bytes": {
"type": "integer",
"description": "Maximum size of direct response body."
}
},
"required": ["name", "virtual_hosts"],
"$defs": {
"VirtualHost": {
"type": "object",
"description": "A virtual host groups routes under a set of domain names.",
"properties": {
"name": {
"type": "string",
"description": "Logical name for the virtual host."
},
"domains": {
"type": "array",
"description": "List of domains (host/authority header) that will match this virtual host. Wildcards are supported.",
"items": {
"type": "string"
},
"minItems": 1
},
"routes": {
"type": "array",
"description": "List of routes matched in order.",
"items": {
"$ref": "#/$defs/Route"
}
},
"require_tls": {
"type": "string",
"description": "Whether TLS is required for this virtual host.",
"enum": ["NONE", "EXTERNAL_ONLY", "ALL"]
},
"rate_limits": {
"type": "array",
"description": "Rate limit configurations for the virtual host.",
"items": {
"$ref": "#/$defs/RateLimit"
}
},
"request_headers_to_add": {
"type": "array",
"items": {
"$ref": "#/$defs/HeaderValueOption"
}
},
"request_headers_to_remove": {
"type": "array",
"items": { "type": "string" }
},
"response_headers_to_add": {
"type": "array",
"items": {
"$ref": "#/$defs/HeaderValueOption"
}
},
"response_headers_to_remove": {
"type": "array",
"items": { "type": "string" }
},
"cors": {
"$ref": "#/$defs/CorsPolicy"
},
"retry_policy": {
"$ref": "#/$defs/RetryPolicy"
},
"hedge_policy": {
"type": "object",
"properties": {
"initial_requests": { "type": "integer" },
"additional_request_chance": {
"type": "object",
"properties": {
"numerator": { "type": "integer" },
"denominator": { "type": "string" }
}
}
}
}
},
"required": ["name", "domains", "routes"]
},
"Route": {
"type": "object",
"description": "A route entry that matches requests and specifies an action.",
"properties": {
"name": {
"type": "string",
"description": "Name assigned to the route for logging and debugging."
},
"match": {
"type": "object",
"description": "Matching criteria for the route.",
"properties": {
"prefix": {
"type": "string",
"description": "Match requests with this URL path prefix."
},
"path": {
"type": "string",
"description": "Match requests with this exact URL path."
},
"safe_regex": {
"type": "object",
"description": "Match requests with a regex URL path.",
"properties": {
"google_re2": { "type": "object" },
"regex": { "type": "string" }
}
},
"case_sensitive": {
"type": "boolean",
"description": "Whether path matching is case sensitive.",
"default": true
},
"headers": {
"type": "array",
"description": "Header match criteria.",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"string_match": { "type": "object" },
"exact_match": { "type": "string" },
"prefix_match": { "type": "string" },
"suffix_match": { "type": "string" },
"present_match": { "type": "boolean" },
"invert_match": { "type": "boolean" }
},
"required": ["name"]
}
},
"query_parameters": {
"type": "array",
"description": "Query parameter match criteria.",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"string_match": { "type": "object" },
"present_match": { "type": "boolean" }
},
"required": ["name"]
}
},
"grpc": {
"type": "object",
"description": "Match only gRPC requests."
}
}
},
"route": {
"type": "object",
"description": "Forward the request to an upstream cluster.",
"properties": {
"cluster": {
"type": "string",
"description": "Target upstream cluster name."
},
"weighted_clusters": {
"type": "object",
"description": "Route to multiple clusters with weights.",
"properties": {
"clusters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"weight": { "type": "integer" }
},
"required": ["name", "weight"]
}
},
"total_weight": { "type": "integer" }
}
},
"cluster_header": {
"type": "string",
"description": "Route to cluster specified by a request header."
},
"timeout": {
"type": "string",
"description": "Request timeout for this route."
},
"idle_timeout": {
"type": "string",
"description": "Idle timeout for this route."
},
"retry_policy": {
"$ref": "#/$defs/RetryPolicy"
},
"prefix_rewrite": {
"type": "string",
"description": "Rewrite the URL prefix before forwarding."
},
"regex_rewrite": {
"type": "object",
"properties": {
"pattern": {
"type": "object",
"properties": {
"google_re2": { "type": "object" },
"regex": { "type": "string" }
}
},
"substitution": { "type": "string" }
}
},
"host_rewrite_literal": {
"type": "string",
"description": "Rewrite the host header before forwarding."
},
"auto_host_rewrite": {
"type": "boolean",
"description": "Automatically rewrite host to upstream host."
},
"hash_policy": {
"type": "array",
"description": "Hash policies for ring hash and maglev load balancers.",
"items": {
"type": "object",
"properties": {
"header": {
"type": "object",
"properties": {
"header_name": { "type": "string" }
}
},
"cookie": {
"type": "object",
"properties": {
"name": { "type": "string" },
"ttl": { "type": "string" },
"path": { "type": "string" }
}
},
"connection_properties": {
"type": "object",
"properties": {
"source_ip": { "type": "boolean" }
}
},
"terminal": { "type": "boolean" }
}
}
},
"rate_limits": {
"type": "array",
"items": {
"$ref": "#/$defs/RateLimit"
}
}
}
},
"redirect": {
"type": "object",
"description": "Return an HTTP redirect response.",
"properties": {
"https_redirect": { "type": "boolean" },
"scheme_redirect": { "type": "string" },
"host_redirect": { "type": "string" },
"port_redirect": { "type": "integer" },
"path_redirect": { "type": "string" },
"prefix_rewrite": { "type": "string" },
"response_code": {
"type": "integer",
"enum": [301, 302, 303, 307, 308]
},
"strip_query": { "type": "boolean" }
}
},
"direct_response": {
"type": "object",
"description": "Return a direct response without proxying.",
"properties": {
"status": {
"type": "integer",
"description": "HTTP response status code.",
"minimum": 100,
"maximum": 599
},
"body": {
"type": "object",
"properties": {
"inline_string": { "type": "string" },
"inline_bytes": { "type": "string" },
"filename": { "type": "string" }
}
}
},
"required": ["status"]
},
"metadata": {
"type": "object",
"description": "Route metadata for access logging and extensions.",
"additionalProperties": true
},
"decorator": {
"type": "object",
"description": "Decorator for the matched route for tracing.",
"properties": {
"operation": {
"type": "string",
"description": "Operation name for tracing."
}
}
},
"request_headers_to_add": {
"type": "array",
"items": { "$ref": "#/$defs/HeaderValueOption" }
},
"response_headers_to_add": {
"type": "array",
"items": { "$ref": "#/$defs/HeaderValueOption" }
}
},
"required": ["match"]
},
"RetryPolicy": {
"type": "object",
"description": "HTTP retry policy.",
"properties": {
"retry_on": {
"type": "string",
"description": "Comma-separated retry conditions (e.g., '5xx,connect-failure,retriable-4xx')."
},
"num_retries": {
"type": "integer",
"description": "Maximum number of retries.",
"minimum": 0
},
"per_try_timeout": {
"type": "string",
"description": "Timeout per retry attempt."
},
"per_try_idle_timeout": {
"type": "string"
},
"retry_back_off": {
"type": "object",
"properties": {
"base_interval": { "type": "string" },
"max_interval": { "type": "string" }
}
},
"retriable_status_codes": {
"type": "array",
"items": { "type": "integer" }
},
"retriable_headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"exact_match": { "type": "string" }
}
}
},
"retry_host_predicate": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" }
}
}
},
"host_selection_retry_max_attempts": {
"type": "integer"
}
}
},
"RateLimit": {
"type": "object",
"description": "Rate limit configuration.",
"properties": {
"stage": {
"type": "integer"
},
"disable_key": {
"type": "string"
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source_cluster": { "type": "object" },
"destination_cluster": { "type": "object" },
"request_headers": {
"type": "object",
"properties": {
"header_name": { "type": "string" },
"descriptor_key": { "type": "string" }
}
},
"remote_address": { "type": "object" },
"generic_key": {
"type": "object",
"properties": {
"descriptor_value": { "type": "string" }
}
}
}
}
}
}
},
"CorsPolicy": {
"type": "object",
"description": "CORS policy configuration.",
"properties": {
"allow_origin_string_match": {
"type": "array",
"items": {
"type": "object",
"properties": {
"exact": { "type": "string" },
"prefix": { "type": "string" },
"suffix": { "type": "string" },
"safe_regex": { "type": "object" },
"contains": { "type": "string" }
}
}
},
"allow_methods": { "type": "string" },
"allow_headers": { "type": "string" },
"expose_headers": { "type": "string" },
"max_age": { "type": "string" },
"allow_credentials": { "type": "boolean" }
}
},
"HeaderValueOption": {
"type": "object",
"description": "Header name/value pair with append control.",
"properties": {
"header": {
"type": "object",
"properties": {
"key": { "type": "string" },
"value": { "type": "string" }
},
"required": ["key", "value"]
},
"append": {
"type": "boolean",
"description": "Whether to append to existing headers."
},
"append_action": {
"type": "string",
"enum": ["APPEND_IF_EXISTS_OR_ADD", "ADD_IF_ABSENT", "OVERWRITE_IF_EXISTS_OR_ADD", "OVERWRITE_IF_EXISTS"]
}
}
}
}
}
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/envoy-route-configuration"
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.