---
title: "Upsert a Route"
url: "https://nov18-dev.movespot.fyi/apis/konnect-control-planes-configuration-3/versions/4a9ee72f-47ac-4061-9b08-3290c8d0ce93/operations/upsert-route"
---

> Full API specification: https://nov18-dev.movespot.fyi/apis/konnect-control-planes-configuration-3/versions/4a9ee72f-47ac-4061-9b08-3290c8d0ce93.md

# Upsert a Route

`PUT` `/control-planes/{controlPlaneId}/core-entities/routes/{RouteId}`

Operation ID: `upsert-route`

Create or Update Route using ID or name.

## Path parameters

- `RouteId` (string, required) - ID of the Route to lookup
- `controlPlaneId` (string, uuid, required) - The UUID of your control plane. This variable is available in the Konnect manager.

## Request body (required)

Content types: `application/json`

## Responses

- `200` - Successfully upserted Route
- `401` - Unauthorized

## OpenAPI definition

```yaml
openapi: 3.1.0
info:
  title: Konnect Control Planes Configuration
  version: 3.14.0
servers:
  - url: https://us.api.konghq.com/v2
    description: United-States Production region
  - url: https://eu.api.konghq.com/v2
    description: Europe Production region
  - url: https://au.api.konghq.com/v2
    description: Australia Production region
  - url: https://me.api.konghq.com/v2
    description: Middle-East Production region
  - url: https://in.api.konghq.com/v2
    description: India Production region
  - url: https://sg.api.konghq.com/v2
    description: Singapore Production region
paths:
  /control-planes/{controlPlaneId}/core-entities/routes/{RouteId}:
    parameters:
      - $ref: "#/components/parameters/RouteId"
      - $ref: "#/components/parameters/controlPlaneId"
    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"
      tags:
        - Routes
security:
  - konnectAccessToken: []
  - personalAccessToken: []
components:
  parameters:
    RouteId:
      description: ID of the Route to lookup
      example: a4326a41-aa12-44e3-93e4-6b6e58bfb9d7
      in: path
      name: RouteId
      required: true
      schema:
        type: string
    controlPlaneId:
      name: controlPlaneId
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 9524ec7d-36d9-465d-a8c5-83a3c9390458
      description: The UUID of your control plane. This variable is available in the
        Konnect manager.
  schemas:
    Route:
      oneOf:
        - $ref: "#/components/schemas/RouteJson"
        - $ref: "#/components/schemas/RouteExpression"
    RouteJson:
      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
    RouteExpression:
      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
        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
        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
          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
    GatewayUnauthorizedError:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
      required:
        - message
        - status
  responses:
    HTTP401Error:
      description: Unauthorized
      content:
        application/json:
          examples:
            DuplicateApiKey:
              summary: Duplicate API key found
              value:
                message: Duplicate API key found
                status: 401
            InvalidAuthCred:
              summary: Invalid authentication credentials
              value:
                message: Unauthorized
                status: 401
            NoAPIKey:
              summary: No API key found
              value:
                message: No API key found in request
                status: 401
          schema:
            $ref: "#/components/schemas/GatewayUnauthorizedError"
  securitySchemes:
    konnectAccessToken:
      type: http
      scheme: bearer
      description: The Konnect access token is meant to be used by the Konnect
        dashboard and the decK CLI to authenticate with.
    personalAccessToken:
      type: http
      scheme: bearer
      description: The personal access token is meant to be used as an alternative to
        basic-auth when accessing Konnect via APIs. You can generate a Personal
        Access Token (PAT) from the personal access token page in the Konnect
        dashboard.
```
