Kong Routes API
Route entities define rules to match client requests. Each route is associated with a service, and a service may have multiple routes associated to it. Every request matching a given route will be proxied to the associated service. You need at least one matching rule that applies to the protocol being matched by the route. The combination of routes and services, and the separation of concerns between them, offers a powerful routing mechanism with which it is possible to define fine-grained entrypoints in Kong Gateway leading to different upstream services of your infrastructure. Depending on the protocol, one of the following attributes must be set: - `http`: At least one of `methods`, `hosts`, `headers`, or `paths` - `https`: At least one of `methods`, `hosts`, `headers`, `paths`, or `snis` - `tcp`: At least one of `sources` or `destinations` - `tls`: at least one of `sources`, `destinations`, or `snis` - `tls_passthrough`: set `snis` - `grpc`: At least one of `hosts`, `headers`, or `paths` - `grpcs`: At least one of `hosts`, `headers`, `paths`, or `snis` - `ws`: At least one of `hosts`, `headers`, or `paths` - `wss`: At least one of `hosts`, `headers`, `paths`, or `snis` A route can't have both `tls` and `tls_passthrough` protocols at same time. Learn more about the router: - [Configure routes using expressions](https://developer.konghq.com/gateway/routing/expressions/)
Documentation
Specifications
SDKs
Schemas & Data
Other Resources
openapi: 3.1.0
info:
contact:
email: support@konghq.com
name: Kong Inc
url: https://konghq.com
description: 'OpenAPI 3.0 spec for Kong Gateway''s Admin API.
You can learn more about Kong Gateway at [developer.konghq.com](https://developer.konghq.com).
Give Kong a star at the [Kong/kong](https://github.com/kong/kong) repository.'
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
title: Kong Enterprise Admin ACLs Routes API
version: 3.14.0
servers:
- description: Default Admin API URL
url: '{protocol}://{hostname}:{port}{path}'
variables:
hostname:
default: localhost
description: Hostname for Kong's Admin API
path:
default: /
description: Base path for Kong's Admin API
port:
default: '8001'
description: Port for Kong's Admin API
protocol:
default: http
description: Protocol for requests to Kong's Admin API
enum:
- http
- https
security:
- adminToken: []
tags:
- description: "Route entities define rules to match client requests. Each route is associated with a service, and a service may have multiple routes associated to it. Every request matching a given route will be proxied to the associated service. You need at least one matching rule that applies to the protocol being matched by the route.\n<br><br>\nThe combination of routes and services, and the separation of concerns between them, offers a powerful routing mechanism with which it is possible to define fine-grained entrypoints in Kong Gateway leading to different upstream services of your infrastructure.\n<br><br>\nDepending on the protocol, one of the following attributes must be set:\n<br>\n\n- `http`: At least one of `methods`, `hosts`, `headers`, or `paths`\n- `https`: At least one of `methods`, `hosts`, `headers`, `paths`, or `snis`\n- `tcp`: At least one of `sources` or `destinations`\n- `tls`: at least one of `sources`, `destinations`, or `snis`\n- `tls_passthrough`: set `snis`\n- `grpc`: At least one of `hosts`, `headers`, or `paths`\n- `grpcs`: At least one of `hosts`, `headers`, `paths`, or `snis`\n- `ws`: At least one of `hosts`, `headers`, or `paths`\n- `wss`: At least one of `hosts`, `headers`, `paths`, or `snis`\n <br>\n A route can't have both `tls` and `tls_passthrough` protocols at same time.\n <br><br>\n Learn more about the router:\n- [Configure routes using expressions](https://developer.konghq.com/gateway/routing/expressions/)\n"
name: Routes
paths:
/{workspace}/routes:
post:
x-speakeasy-entity-operation:
terraform-datasource: null
terraform-resource: Route#create
operationId: create-route
summary: Create a new Route
description: Create a new Route
parameters:
- $ref: '#/components/parameters/Workspace'
requestBody:
description: Description of the new Route for creation
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RouteJson'
responses:
'201':
description: Successfully created Route
content:
application/json:
schema:
$ref: '#/components/schemas/RouteJson'
'401':
$ref: '#/components/responses/HTTP401Error'
tags:
- Routes
/{workspace}/routes#RouteExpression:
post:
x-speakeasy-entity-operation:
terraform-datasource: null
terraform-resource: RouteExpression#create
operationId: create-route-RouteExpression
summary: Create a new Route
description: Create a new Route
parameters:
- $ref: '#/components/parameters/Workspace'
requestBody:
description: Description of the new Route for creation
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RouteExpression'
responses:
'201':
description: Successfully created Route
content:
application/json:
schema:
$ref: '#/components/schemas/RouteExpression'
'401':
$ref: '#/components/responses/HTTP401Error'
tags:
- Routes
/{workspace}/routes/{RouteIdOrName}:
parameters:
- $ref: '#/components/parameters/RouteIdOrName'
delete:
x-speakeasy-entity-operation:
terraform-datasource: null
terraform-resource: Route#delete
operationId: delete-route
summary: Delete a Route
description: Delete a Route
parameters:
- $ref: '#/components/parameters/RouteIdOrName'
- $ref: '#/components/parameters/Workspace'
responses:
'204':
description: Successfully deleted Route or the resource didn't exist
'401':
$ref: '#/components/responses/HTTP401Error'
tags:
- Routes
get:
x-speakeasy-entity-operation:
terraform-datasource: null
terraform-resource: Route#read
operationId: get-route
summary: Get a Route
description: Get a Route using ID or name.
parameters:
- $ref: '#/components/parameters/Workspace'
responses:
'200':
description: Successfully fetched Route
content:
application/json:
schema:
$ref: '#/components/schemas/RouteJson'
'401':
$ref: '#/components/responses/HTTP401Error'
'404':
description: Resource does not exist
tags:
- Routes
put:
x-speakeasy-entity-operation:
terraform-datasource: null
terraform-resource: Route#update
operationId: upsert-route
summary: Upsert a Route
description: Create or Update Route using ID or name.
parameters:
- $ref: '#/components/parameters/Workspace'
requestBody:
description: Description of the Route
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RouteJson'
responses:
'200':
description: Successfully upserted Route
content:
application/json:
schema:
$ref: '#/components/schemas/RouteJson'
'401':
$ref: '#/components/responses/HTTP401Error'
tags:
- Routes
/{workspace}/routes/{RouteIdOrName}#RouteExpression:
parameters:
- $ref: '#/components/parameters/RouteIdOrName'
delete:
x-speakeasy-entity-operation:
terraform-datasource: null
terraform-resource: RouteExpression#delete
operationId: delete-route-RouteExpression
summary: Delete a Route
description: Delete a Route
parameters:
- $ref: '#/components/parameters/RouteIdOrName'
- $ref: '#/components/parameters/Workspace'
responses:
'204':
description: Successfully deleted Route or the resource didn't exist
'401':
$ref: '#/components/responses/HTTP401Error'
tags:
- Routes
get:
x-speakeasy-entity-operation:
terraform-datasource: null
terraform-resource: RouteExpression#read
operationId: get-route-RouteExpression
summary: Get a Route
description: Get a Route using ID or name.
parameters:
- $ref: '#/components/parameters/Workspace'
responses:
'200':
description: Successfully fetched Route
content:
application/json:
schema:
$ref: '#/components/schemas/RouteExpression'
'401':
$ref: '#/components/responses/HTTP401Error'
'404':
description: Resource does not exist
tags:
- Routes
put:
x-speakeasy-entity-operation:
terraform-datasource: null
terraform-resource: RouteExpression#update
operationId: upsert-route-RouteExpression
summary: Upsert a Route
description: Create or Update Route using ID or name.
parameters:
- $ref: '#/components/parameters/Workspace'
requestBody:
description: Description of the Route
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RouteExpression'
responses:
'200':
description: Successfully upserted Route
content:
application/json:
schema:
$ref: '#/components/schemas/RouteExpression'
'401':
$ref: '#/components/responses/HTTP401Error'
tags:
- Routes
/v2/control-planes/{controlPlaneId}/core-entities/routes:
parameters:
- $ref: '#/components/parameters/controlPlaneId'
get:
operationId: list-route
summary: List all Routes
description: List all Routes
parameters:
- $ref: '#/components/parameters/PaginationSize'
- $ref: '#/components/parameters/PaginationOffset'
- $ref: '#/components/parameters/PaginationTagsFilter'
- $ref: '#/components/parameters/NameContainsFilter'
- $ref: '#/components/parameters/NameEqualsFilter'
responses:
'200':
description: A successful response listing Routes
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Route'
next:
$ref: '#/components/schemas/PaginationNextResponse'
offset:
$ref: '#/components/schemas/PaginationOffsetResponse'
'401':
$ref: '#/components/responses/HTTP401Error_2'
tags:
- Routes
post:
operationId: create-route
summary: Create a new Route
description: Create a new Route
requestBody:
description: Description of the new Route for creation
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Route'
responses:
'201':
description: Successfully created Route
content:
application/json:
schema:
$ref: '#/components/schemas/Route'
'401':
$ref: '#/components/responses/HTTP401Error_2'
tags:
- Routes
/v2/control-planes/{controlPlaneId}/core-entities/routes/{RouteId}:
parameters:
- $ref: '#/components/parameters/RouteId'
- $ref: '#/components/parameters/controlPlaneId'
delete:
operationId: delete-route
summary: Delete a Route
description: Delete a Route
parameters:
- $ref: '#/components/parameters/RouteId'
responses:
'204':
description: Successfully deleted Route or the resource didn't exist
'401':
$ref: '#/components/responses/HTTP401Error_2'
tags:
- Routes
get:
operationId: get-route
summary: Get a Route
description: Get a Route using ID or name.
responses:
'200':
description: Successfully fetched Route
content:
application/json:
schema:
$ref: '#/components/schemas/Route'
'401':
$ref: '#/components/responses/HTTP401Error_2'
'404':
description: Resource does not exist
tags:
- Routes
put:
operationId: upsert-route
summary: Upsert a Route
description: Create or Update Route using ID or name.
requestBody:
description: Description of the Route
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Route'
responses:
'200':
description: Successfully upserted Route
content:
application/json:
schema:
$ref: '#/components/schemas/Route'
'401':
$ref: '#/components/responses/HTTP401Error_2'
tags:
- Routes
/v2/control-planes/{controlPlaneId}/core-entities/services/{ServiceId}/routes:
parameters:
- $ref: '#/components/parameters/controlPlaneId'
get:
operationId: list-route-with-service
summary: List all Routes associated with a Service
description: List all Routes associated with a Service
parameters:
- $ref: '#/components/parameters/ServiceId'
- $ref: '#/components/parameters/PaginationSize'
- $ref: '#/components/parameters/PaginationOffset'
- $ref: '#/components/parameters/PaginationTagsFilter'
responses:
'200':
description: A successful response listing Routes
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Route'
next:
$ref: '#/components/schemas/PaginationNextResponse'
offset:
$ref: '#/components/schemas/PaginationOffsetResponse'
tags:
- Routes
post:
operationId: create-route-with-service
summary: Create a new Route associated with a Service
description: Create a new Route associated with a Service
parameters:
- $ref: '#/components/parameters/ServiceId'
requestBody:
description: Description of new Route for creation
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RouteWithoutParents'
responses:
'201':
description: Successfully created Route
content:
application/json:
schema:
$ref: '#/components/schemas/Route'
tags:
- Routes
/v2/control-planes/{controlPlaneId}/core-entities/services/{ServiceId}/routes/{RouteId}:
parameters:
- $ref: '#/components/parameters/controlPlaneId'
delete:
operationId: delete-route-with-service
summary: Delete a a Route associated with a Service
description: Delete a a Route associated with a Service using ID or name.
parameters:
- $ref: '#/components/parameters/ServiceId'
- $ref: '#/components/parameters/RouteId'
responses:
'204':
description: Successfully deleted Route or the resource didn't exist
tags:
- Routes
get:
operationId: get-route-with-service
summary: Get a Route associated with a Service
description: Get a Route associated with a Service using ID or name.
parameters:
- $ref: '#/components/parameters/ServiceId'
- $ref: '#/components/parameters/RouteId'
responses:
'200':
description: Successfully fetched Route
content:
application/json:
schema:
$ref: '#/components/schemas/Route'
'404':
description: Resource does not exist
tags:
- Routes
put:
operationId: upsert-route-with-service
summary: Upsert a Route associated with a Service
description: Create or Update a Route associated with a Service using ID or name.
parameters:
- $ref: '#/components/parameters/ServiceId'
- $ref: '#/components/parameters/RouteId'
requestBody:
description: Description of the Route
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RouteWithoutParents'
responses:
'200':
description: Successfully upserted Route
content:
application/json:
schema:
$ref: '#/components/schemas/Route'
tags:
- Routes
components:
schemas:
RouteWithoutParents:
oneOf:
- $ref: '#/components/schemas/RouteJson_2'
- $ref: '#/components/schemas/RouteExpression_2'
RouteExpression_2:
description: Route entities define rules to match client requests. Each Route is associated with a Service, and a Service may have multiple Routes associated to it. Every request matching a given Route will be proxied to its associated Service. The combination of Routes and Services (and the separation of concerns between them) offers a powerful routing mechanism with which it is possible to define fine-grained entry-points in Kong leading to different upstream services of your infrastructure. You need at least one matching rule that applies to the protocol being matched by the Route.
type: object
properties:
created_at:
description: Unix epoch when the resource was created.
type: integer
nullable: true
expression:
description: Use Router Expression to perform route match. This option is only available when `router_flavor` is set to `expressions`.
type: string
nullable: true
https_redirect_status_code:
description: 'The status code Kong responds with when all properties of a Route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS`. `Location` header is injected by Kong if the field is set to 301, 302, 307 or 308. Note: This config applies only if the Route is configured to only accept the `https` protocol.'
type: integer
default: 426
enum:
- 301
- 302
- 307
- 308
- 426
nullable: true
x-speakeasy-unknown-values: allow
id:
description: A string representing a UUID (universally unique identifier).
type: string
nullable: true
name:
description: The name of the Route. Route names must be unique, and they are case sensitive. For example, there can be two different Routes named "test" and "Test".
type: string
nullable: true
path_handling:
description: Controls how the Service path, Route path and requested path are combined when sending a request to the upstream. See above for a detailed description of each behavior.
type: string
default: v0
enum:
- v0
- v1
nullable: true
x-speakeasy-unknown-values: allow
preserve_host:
description: When matching a Route via one of the `hosts` domain names, use the request `Host` header in the upstream request headers. If set to `false`, the upstream `Host` header will be that of the Service's `host`.
type: boolean
default: false
nullable: true
priority:
description: A number used to specify the matching order for expression routes. The higher the `priority`, the sooner an route will be evaluated. This field is ignored unless `expression` field is set.
type: integer
default: 0
maximum: 70368744177663
minimum: 0
nullable: true
protocols:
description: An array of the protocols this Route should allow. See the [Route Object](#route-object) section for a list of accepted protocols. When set to only `"https"`, HTTP requests are answered with an upgrade error. When set to only `"http"`, HTTPS requests are answered with an error.
type: array
items:
description: A string representing a protocol, such as HTTP or HTTPS.
enum:
- grpc
- grpcs
- http
- https
- tcp
- tls
- tls_passthrough
- udp
- ws
- wss
type: string
x-speakeasy-unknown-values: allow
default:
- https
minLength: 1
nullable: true
request_buffering:
description: Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding.
type: boolean
default: true
nullable: true
response_buffering:
description: Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding.
type: boolean
default: true
nullable: true
service:
description: The Service this Route is associated to. This is where the Route proxies traffic to.
type: object
nullable: true
properties:
id:
type: string
x-foreign: true
strip_path:
description: When matching a Route via one of the `paths`, strip the matching prefix from the upstream request URL.
type: boolean
default: true
nullable: true
tags:
description: An optional set of strings associated with the Route 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
additionalProperties: false
RouteJson:
x-speakeasy-entity: Route
description: Route entities define rules to match client requests. Each Route is associated with a Service, and a Service may have multiple Routes associated to it. Every request matching a given Route will be proxied to its associated Service. The combination of Routes and Services (and the separation of concerns between them) offers a powerful routing mechanism with which it is possible to define fine-grained entry-points in Kong leading to different upstream services of your infrastructure. You need at least one matching rule that applies to the protocol being matched by the Route.
type: object
properties:
created_at:
description: Unix epoch when the resource was created.
type: integer
nullable: true
destinations:
description: A list of IP destinations of incoming connections that match this Route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port".
type: array
items:
properties:
ip:
description: A string representing an IP address or CIDR block, such as 192.168.1.1 or 192.168.0.0/16.
type: string
port:
description: An integer representing a port number between 0 and 65535, inclusive.
type: integer
maximum: 65535
minimum: 0
type: object
nullable: true
headers:
description: 'One or more lists of values indexed by header name that will cause this Route to match if present in the request. The `Host` header cannot be used with this attribute: hosts should be specified using the `hosts` attribute. When `headers` contains only one value and that value starts with the special prefix `~*`, the value is interpreted as a regular expression.'
type: object
additionalProperties:
items:
type: string
type: array
nullable: true
hosts:
description: A list of domain names that match this Route. Note that the hosts value is case sensitive.
type: array
items:
type: string
nullable: true
https_redirect_status_code:
description: 'The status code Kong responds with when all properties of a Route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS`. `Location` header is injected by Kong if the field is set to 301, 302, 307 or 308. Note: This config applies only if the Route is configured to only accept the `https` protocol.'
type: integer
default: 426
enum:
- 301
- 302
- 307
- 308
- 426
nullable: true
id:
description: A string representing a UUID (universally unique identifier).
type: string
nullable: true
methods:
description: A list of HTTP methods that match this Route.
type: array
items:
description: A string representing an HTTP method, such as GET, POST, PUT, or DELETE. The string must contain only uppercase letters.
type: string
nullable: true
name:
description: The name of the Route. Route names must be unique, and they are case sensitive. For example, there can be two different Routes named "test" and "Test".
type: string
nullable: true
path_handling:
description: Controls how the Service path, Route path and requested path are combined when sending a request to the upstream. See above for a detailed description of each behavior.
type: string
default: v0
enum:
- v0
- v1
nullable: true
paths:
description: A list of paths that match this Route.
type: array
items:
description: A string representing a router path. It must start with a forward slash ('/') for a fixed path, or the sequence '~/' for a regex path. It must not have empty segments.
type: string
nullable: true
preserve_host:
description: When matching a Route via one of the `hosts` domain names, use the request `Host` header in the upstream request headers. If set to `false`, the upstream `Host` header will be that of the Service's `host`.
type: boolean
default: false
nullable: true
protocols:
description: An array of the protocols this Route should allow. See the [Route Object](#route-object) section for a list of accepted protocols. When set to only `"https"`, HTTP requests are answered with an upgrade error. When set to only `"http"`, HTTPS requests are answered with an error.
type: array
items:
description: A string representing a protocol, such as HTTP or HTTPS.
enum:
- grpc
- grpcs
- http
- https
- tcp
- tls
- tls_passthrough
- udp
- ws
- wss
type: string
default:
- https
minLength: 1
nullable: true
regex_priority:
description: A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same `regex_priority`, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones).
type: integer
default: 0
nullable: true
request_buffering:
description: Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding.
type: boolean
default: true
nullable: true
response_buffering:
description: Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding.
type: boolean
default: true
nullable: true
service:
description: The Service this Route is associated to. This is where the Route proxies traffic to.
type: object
nullable: true
properties:
id:
type: string
x-foreign: true
snis:
description: A list of SNIs that match this Route when using stream routing.
type: array
items:
description: A string representing a wildcard host name, such as *.example.com.
type: string
nullable: true
sources:
description: A list of IP sources of incoming connections that match this Route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port".
type: array
items:
properties:
ip:
description: A string representing an IP address or CIDR block, such as 192.168.1.1 or 192.168.0.0/16.
type: string
port:
description: An integer representing a port number between 0 and 65535, inclusive.
type: integer
maximum: 65535
minimum: 0
type: object
nullable: true
strip_path:
description: When matching a Route via one of the `paths`, strip the matching prefix from the upstream request URL.
type: boolean
default: true
nullable: true
tags:
description: An optional set of strings associated with the Route 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
example:
hosts:
- foo.example.com
- foo.example.us
id: 56c4566c-14cc-4132-9011-4139fcbbe50a
name: example-route
paths:
- /v1
- /v2
service:
id: bd380f99-659d-415e-b0e7-72ea05df3218
additionalProperties: false
Route:
oneOf:
- $ref: '#/components/schemas/RouteJson_2'
- $ref: '#/components/schemas/RouteExpression_2'
PaginationNextResponse:
description: URI to the next page (may be null)
type: string
RouteJson_2:
description: Route entities define rules to match client requests. Each Route is associated with a Service, and a Service may have multiple Routes associated to it. Every request matching a given Route will be proxied to its associated Service. The combination of Routes and Services (and the separation of concerns between them) offers a powerful routing mechanism with which it is possible to define fine-grained entry-points in Kong leading to different upstream services of your infrastructure. You need at least one matching rule that applies to the protocol being matched by the Route.
type: object
properties:
created_at:
description: Unix epoch when the resource was created.
type: integer
nullable: true
destinations:
description: A list of IP destinations of incoming connections that match this Route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port".
type: array
items:
properties:
ip:
description: A string representing an IP address or CIDR block, such as 192.168.1.1 or 192.168.0.0/16.
type: string
port:
description: An integer representing a port number between 0 and 65535, inclusive.
type: integer
maximum: 65535
minimum: 0
type: object
nullable: true
headers:
description: 'One or more lists of values indexed by header name that will cause this Route to match if present in the request. The `Host` header cannot be used with this attribute: hosts should be specified using the `hosts` attribute. When `headers` contains only one value and that value starts with the special prefix `~*`, the value is interpreted as a regular expression.'
type: object
additionalProperties:
items:
type: string
type: array
nullable: true
hosts:
description: A list of domain names that match this Route. Note that the hosts value is case sensitive.
type: array
items:
type: string
nullable: true
https_redirect_status_code:
description: 'The status code Kong responds with when all properties of a Route match except the protocol i.e. if the protocol of the request is
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kong/refs/heads/main/openapi/kong-routes-api-openapi.yml