---
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}`

## Request

- Base URL: `https://global.api.konghq.com`
- URL: `https://global.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/routes/{RouteId}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

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

## Changes

- **2026-04-17** `c80d57ed14ab`: 4 info
  - the `protocols` request property default value changed from `http, https` to `https`
  - the `protocols` request property default value changed from `http, https` to `https`
  - the `protocols` response's property default value changed from `http, https` to `https` for the status `200`
  - the `protocols` response's property default value changed from `http, https` to `https` for the status `200`
- **2025-10-30** `845120e19d45`: 4 breaking
  - the request property `oneOf[#/components/schemas/RouteJson]/destinations/items/ip` became not nullable
  - the request property `oneOf[#/components/schemas/RouteJson]/destinations/items/port` became not nullable
  - the request property `oneOf[#/components/schemas/RouteJson]/sources/items/ip` became not nullable
  - the request property `oneOf[#/components/schemas/RouteJson]/sources/items/port` became not nullable
- **2025-09-16** `ddf026fbd25b`: 2 breaking, 6 warning
  - the `oneOf[#/components/schemas/RouteExpression]/protocols` request property's minLength was increased from `0` to `1`
  - the `oneOf[#/components/schemas/RouteJson]/protocols` request property's minLength was increased from `0` to `1`
  - the `oneOf[#/components/schemas/RouteExpression]/priority` request property's max was set to `70368744177663.00`
  - the `oneOf[#/components/schemas/RouteJson]/destinations/items/port` request property's max was set to `65535.00`
  - …4 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/kong/apis/konnect-api-go-sdk/changes/v2/control-planes/:controlPlaneId/core-entities/routes/:RouteId/put.md)

---

[API](https://skmtc.dev/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.dev/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc.dev/kong/apis/konnect-api-go-sdk/revisions/7aab863a6daa?raw)