--- title: "Upsert a Route" method: PUT path: "/v2/control-planes/{controlPlaneId}/core-entities/routes/{RouteId}" tags: ["Routes"] --- # Upsert a Route `PUT /v2/control-planes/{controlPlaneId}/core-entities/routes/{RouteId}` Create or Update Route using ID or name. ## Request body - union - RouteJson — 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. - `created_at` integer, nullable — Unix epoch when the resource was created. - `destinations` object[], nullable — 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". - `ip` string — A string representing an IP address or CIDR block, such as 192.168.1.1 or 192.168.0.0/16. - `port` integer — An integer representing a port number between 0 and 65535, inclusive. - `headers` object, nullable — 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. - `hosts` string[], nullable — A list of domain names that match this Route. Note that the hosts value is case sensitive. - `https_redirect_status_code` 301 | 302 | 307 | 308 | 426, nullable — 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. - `id` string, nullable — A string representing a UUID (universally unique identifier). - `methods` string[], nullable — A list of HTTP methods that match this Route. - `name` string, nullable — 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". - `path_handling` 'v0' | 'v1', nullable — 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. - `paths` string[], nullable — A list of paths that match this Route. - `preserve_host` boolean, nullable — 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`. - `protocols` string[], nullable — 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. - `regex_priority` integer, nullable — 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). - `request_buffering` boolean, nullable — 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. - `response_buffering` boolean, nullable — 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. - `service` object, nullable — The Service this Route is associated to. This is where the Route proxies traffic to. - `id` string - `snis` string[], nullable — A list of SNIs that match this Route when using stream routing. - `sources` object[], nullable — 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". - `ip` string — A string representing an IP address or CIDR block, such as 192.168.1.1 or 192.168.0.0/16. - `port` integer — An integer representing a port number between 0 and 65535, inclusive. - `strip_path` boolean, nullable — When matching a Route via one of the `paths`, strip the matching prefix from the upstream request URL. - `tags` string[], nullable — An optional set of strings associated with the Route for grouping and filtering. - `updated_at` integer, nullable — Unix epoch when the resource was last updated. - RouteExpression — 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. - `created_at` integer, nullable — Unix epoch when the resource was created. - `expression` string, nullable — Use Router Expression to perform route match. This option is only available when `router_flavor` is set to `expressions`. - `https_redirect_status_code` 301 | 302 | 307 | 308 | 426, nullable — 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. - `id` string, nullable — A string representing a UUID (universally unique identifier). - `name` string, nullable — 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". - `path_handling` 'v0' | 'v1', nullable — 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. - `preserve_host` boolean, nullable — 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`. - `priority` integer, nullable — 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. - `protocols` string[], nullable — 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. - `request_buffering` boolean, nullable — 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. - `response_buffering` boolean, nullable — 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. - `service` object, nullable — The Service this Route is associated to. This is where the Route proxies traffic to. - `id` string - `strip_path` boolean, nullable — When matching a Route via one of the `paths`, strip the matching prefix from the upstream request URL. - `tags` string[], nullable — An optional set of strings associated with the Route for grouping and filtering. - `updated_at` integer, nullable — Unix epoch when the resource was last updated. ## Response `200` Successfully upserted Route - union - RouteJson — 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. - `created_at` integer, nullable — Unix epoch when the resource was created. - `destinations` object[], nullable — 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". - `ip` string — A string representing an IP address or CIDR block, such as 192.168.1.1 or 192.168.0.0/16. - `port` integer — An integer representing a port number between 0 and 65535, inclusive. - `headers` object, nullable — 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. - `hosts` string[], nullable — A list of domain names that match this Route. Note that the hosts value is case sensitive. - `https_redirect_status_code` 301 | 302 | 307 | 308 | 426, nullable — 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. - `id` string, nullable — A string representing a UUID (universally unique identifier). - `methods` string[], nullable — A list of HTTP methods that match this Route. - `name` string, nullable — 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". - `path_handling` 'v0' | 'v1', nullable — 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. - `paths` string[], nullable — A list of paths that match this Route. - `preserve_host` boolean, nullable — 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`. - `protocols` string[], nullable — 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. - `regex_priority` integer, nullable — 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). - `request_buffering` boolean, nullable — 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. - `response_buffering` boolean, nullable — 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. - `service` object, nullable — The Service this Route is associated to. This is where the Route proxies traffic to. - `id` string - `snis` string[], nullable — A list of SNIs that match this Route when using stream routing. - `sources` object[], nullable — 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". - `ip` string — A string representing an IP address or CIDR block, such as 192.168.1.1 or 192.168.0.0/16. - `port` integer — An integer representing a port number between 0 and 65535, inclusive. - `strip_path` boolean, nullable — When matching a Route via one of the `paths`, strip the matching prefix from the upstream request URL. - `tags` string[], nullable — An optional set of strings associated with the Route for grouping and filtering. - `updated_at` integer, nullable — Unix epoch when the resource was last updated. - RouteExpression — 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. - `created_at` integer, nullable — Unix epoch when the resource was created. - `expression` string, nullable — Use Router Expression to perform route match. This option is only available when `router_flavor` is set to `expressions`. - `https_redirect_status_code` 301 | 302 | 307 | 308 | 426, nullable — 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. - `id` string, nullable — A string representing a UUID (universally unique identifier). - `name` string, nullable — 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". - `path_handling` 'v0' | 'v1', nullable — 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. - `preserve_host` boolean, nullable — 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`. - `priority` integer, nullable — 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. - `protocols` string[], nullable — 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. - `request_buffering` boolean, nullable — 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. - `response_buffering` boolean, nullable — 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. - `service` object, nullable — The Service this Route is associated to. This is where the Route proxies traffic to. - `id` string - `strip_path` boolean, nullable — When matching a Route via one of the `paths`, strip the matching prefix from the upstream request URL. - `tags` string[], nullable — An optional set of strings associated with the Route for grouping and filtering. - `updated_at` integer, nullable — Unix epoch when the resource was last updated. ## Other responses - `401` — Unauthorized --- [API](https://skmtc.net/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.net/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kong/konnect-api-go-sdk/versions/f920f418f552/schema)