---
title: "Create a new Upstream"
url: "https://nov18-dev.movespot.fyi/apis/konnect-runtime-groups-configuration-0/versions/af18902c-58f1-49d7-8ec2-9987b4e0d1bd/operations/create-upstream"
---

> Full API specification: https://nov18-dev.movespot.fyi/apis/konnect-runtime-groups-configuration-0/versions/af18902c-58f1-49d7-8ec2-9987b4e0d1bd.md

# Create a new Upstream

`POST` `/runtime-groups/{runtimeGroupId}/core-entities/upstreams`

Operation ID: `create-upstream`

Create a new Upstream

## Path parameters

- `runtimeGroupId` (string, required) - The ID of your runtime group. This variable is available in the Konnect manager

## Request body

Content types: `application/json`

## Responses

- `200` - Successfully created Upstream
- `400` - Invalid Upstream

## OpenAPI definition

```yaml
openapi: 3.0.0
info:
  title: Konnect Runtime Groups Configuration
  version: 0.0.1
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:
  /runtime-groups/{runtimeGroupId}/core-entities/upstreams:
    parameters:
      - $ref: "#/components/parameters/runtimeGroupId"
    post:
      operationId: create-upstream
      summary: Create a new Upstream
      description: |
        Create a new Upstream
      requestBody:
        $ref: "#/components/requestBodies/upstream-request"
      responses:
        "200":
          description: Successfully created Upstream
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Upstream"
        "400":
          description: Invalid Upstream
          content:
            application/json:
              schema:
                type: object
      tags:
        - Upstreams
security:
  - konnectAccessToken: []
  - personalAccessToken: []
components:
  parameters:
    runtimeGroupId:
      name: runtimeGroupId
      in: path
      required: true
      schema:
        type: string
        example: 9524ec7d-36d9-465d-a8c5-83a3c9390458
      description: The ID of your runtime group. This variable is available in the
        Konnect manager
  requestBodies:
    upstream-request:
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                description: This is a hostname, which must be equal to the `host` of a service.
                type: string
                example: my-upstream
              algorithm:
                description: >
                  Which load balancing algorithm to use. Accepted values are:
                  `consistent-hashing`, `least-connections`,` round-robin`.
                  Default: `round-robin`.
                type: string
                example: round-robin
                default: round-robin
                enum:
                  - consistent-hashing
                  - least-connections
                  - round-robin
              hash_on:
                description: What to use as hashing input. Using none results in a
                  weighted-round-robin scheme with no hashing
                type: string
                default: none
                enum:
                  - none
                  - consumer
                  - ip
                  - cookie
                  - uri_capture
                  - path
                  - query_arg
              hash_fallback:
                description: What to use as hashing input if the primary hash_on does not return
                  a hash (eg. header is missing, or no Consumer identified). Not
                  available if hash_on is set to cookie.
                type: string
                example: none
                default: none
                enum:
                  - none
                  - consumer
                  - ip
                  - cookie
                  - uri_capture
                  - path
                  - query_arg
              hash_on_header:
                description: The header name to take the value from as hash input. Only required
                  when `hash_on` is set to header.
                type: string
                example: none
              hash_fallback_header:
                description: The header name to take the value from as hash input. Only required
                  when hash_fallback is set to header.
                type: string
                example: none
                default: none
              hash_on_cookie:
                description: The cookie name to take the value from as hash input. Only required
                  when `hash_on` or `hash_fallback` is set to `cookie`. If the
                  specified cookie is not in the request, Kong will generate a
                  value and set the cookie in the response.
                type: string
                example: none
              hash_on_cookie_path:
                description: "The cookie path to set in the response headers. Only required when
                  `hash_on` or `hash_fallback` is set to `cookie`. Default:
                  `/`."
                type: string
                example: /
                default: /
              hash_on_query_arg:
                description: The name of the query string argument to take the value from as
                  hash input. Only required when `hash_on` is set to
                  `query_arg`.
                type: string
                example: hash_value
              hash_fallback_query_arg:
                description: The name of the query string argument to take the value from as
                  hash input. Only required when `hash_fallback` is set to
                  `query_arg`.
                type: string
                example: hash_value
              hash_on_uri_capture:
                description: The name of the route URI capture to take the value from as hash
                  input. Only required when `hash_on` is set to `uri_capture`.
                type: string
                example: hash_value
              hash_fallback_uri_capture:
                description: The name of the route URI capture to take the value from as hash
                  input. Only required when `hash_fallback` is set to
                  `uri_capture`.
                type: string
                example: hash_value
              slots:
                description: The number of slots in the load balancer algorithm. If the
                  algorithm is set to `round-robin`, this setting determines the
                  maximum number of slots. If the algorithm is set to
                  `consistent-hashing`, this setting determines the actual
                  number of slots in the algorithm. Accepts an integer in the
                  range 10-65536.
                type: integer
                example: 5000
                default: 10000
                maximum: 65536
                minimum: 10
              healthchecks:
                type: object
                properties:
                  passive:
                    type: object
                    properties:
                      type:
                        description: "Whether to perform passive health checks interpreting HTTP/HTTPS
                          statuses, or just check for TCP connection success. In
                          passive checks, http and https options are equivalent.
                          Accepted values are: `tcp`, `http`, `https`, `grpc`,
                          `grpcs`."
                        type: string
                        example: tcp
                        default: http
                        enum:
                          - tcp
                          - http
                          - https
                          - grpc
                          - grpcs
                      healthy:
                        type: object
                        properties:
                          http_statuses:
                            description: An array of HTTP statuses which represent healthiness when produced
                              by proxied traffic, as observed by passive health
                              checks.  With form-encoded, the notation is
                              `http_statuses[]=200&http_statuses[]=201`. With
                              JSON, use an array.
                            type: array
                            items:
                              type: integer
                              enum:
                                - 200
                                - 201
                                - 202
                                - 203
                                - 204
                                - 205
                                - 206
                                - 207
                                - 208
                                - 226
                                - 300
                                - 301
                                - 302
                                - 303
                                - 304
                                - 305
                                - 306
                                - 307
                                - 308
                            example:
                              - 200
                              - 201
                              - 202
                            default:
                              - 200
                              - 201
                              - 202
                              - 203
                              - 204
                              - 205
                              - 206
                              - 207
                              - 208
                              - 226
                              - 300
                              - 301
                              - 302
                              - 303
                              - 304
                              - 305
                              - 306
                              - 307
                              - 308
                          successes:
                            description: Number of successes in proxied traffic (as defined by
                              `healthchecks.passive.healthy.http_statuses`) to
                              consider a target healthy, as observed by passive
                              health checks.
                            type: integer
                            example: 2
                            default: 0
                      unhealthy:
                        type: object
                        properties:
                          http_statuses:
                            description: An array of HTTP statuses which represent unhealthiness when
                              produced by proxied traffic, as observed by
                              passive health checks. With form-encoded, the
                              notation is
                              `http_statuses[]=429&http_statuses[]=500`. With
                              JSON, use an array.
                            type: array
                            items:
                              type: integer
                              enum:
                                - 429
                                - 500
                                - 503
                            example:
                              - 500
                              - 503
                            default:
                              - 429
                              - 500
                              - 503
                          timeouts:
                            description: Number of timeouts in proxied traffic to consider a target
                              unhealthy, as observed by passive health checks.
                            type: integer
                            example: 1
                            default: 0
                          http_failures:
                            description: Number of HTTP failures in proxied traffic (as defined by
                              `healthchecks.passive.unhealthy.http_statuses`) to
                              consider a target unhealthy, as observed by
                              passive health checks.
                            type: integer
                            example: 3
                            default: 0
                          tcp_failures:
                            description: Number of TCP connection failures to consider a target unhealthy,
                              as observed by passive health checks.
                            type: integer
                            example: 1
                            default: 0
                  active:
                    type: object
                    properties:
                      https_verify_certificate:
                        type: boolean
                      healthy:
                        type: object
                        properties:
                          http_statuses:
                            description: An array of HTTP statuses to consider a success, indicating
                              healthiness, when returned by a probe in active
                              health checks. With form-encoded, the notation is
                              `http_statuses[]=200&http_statuses[]=302`. With
                              JSON, use an array.
                            type: array
                            items:
                              type: integer
                            example:
                              - 200
                              - 201
                            default:
                              - 200
                              - 302
                          successes:
                            description: Number of successes in active probes (as defined by
                              `healthchecks.active.healthy.http_statuses`) to
                              consider a target healthy.
                            type: integer
                            example: 3
                            default: 0
                          interval:
                            description: Interval between active health checks for healthy targets (in
                              seconds). A value of zero indicates that active
                              probes for healthy targets should not be
                              performed.
                            type: integer
                            example: 30
                            default: 0
                      unhealthy:
                        type: object
                        properties:
                          http_failures:
                            description: Number of HTTP failures in active probes (as defined by
                              `healthchecks.active.unhealthy.http_statuses`) to
                              consider a target unhealthy.
                            type: integer
                            example: 2
                            default: 0
                          http_statuses:
                            description: An array of HTTP statuses to consider a failure, indicating
                              unhealthiness, when returned by a probe in active
                              health checks. With form-encoded, the notation is
                              `http_statuses[]=429&http_statuses[]=404`. With
                              JSON, use an array.
                            type: array
                            items:
                              type: integer
                            example:
                              - 400
                              - 404
                            default:
                              - 429
                              - 404
                              - 500
                              - 501
                              - 502
                              - 503
                              - 504
                              - 505
                          timeouts:
                            description: Number of timeouts in active probes to consider a target unhealthy.
                            type: integer
                            example: 2
                            default: 0
                          tcp_failures:
                            description: Number of TCP failures in active probes to consider a target
                              unhealthy.
                            type: integer
                            example: 1
                            default: 0
                          interval:
                            description: Interval between active health checks for unhealthy targets (in
                              seconds). A value of zero indicates that active
                              probes for unhealthy targets should not be
                              performed.
                            type: integer
                            example: 10
                            default: 0
                      type:
                        description: Whether to perform active health checks using HTTP or HTTPS, or
                          just attempt a TCP connection.
                        type: string
                        example: https
                        default: http
                        enum:
                          - tcp
                          - http
                          - https
                          - grpc
                          - grpcs
                      concurrency:
                        description: Number of targets to check concurrently in active health checks.
                        type: integer
                        example: 5
                        default: 10
                      timeout:
                        description: Socket timeout for active health checks (in seconds).
                        type: integer
                        example: 5
                        default: 1
                      http_path:
                        description: Path to use in GET HTTP request to run as a probe on active health
                          checks.
                        type: string
                        default: /
                      https_sni:
                        description: The hostname to use as an SNI (Server Name Identification) when
                          performing active health checks using HTTPS. This is
                          particularly useful when Targets are configured using
                          IPs, so that the target host’s certificate can be
                          verified with the proper SNI.
                        type: string
                  threshold:
                    description: The minimum percentage of the upstream’s targets’ weight that must
                      be available for the whole upstream to be considered
                      healthy.
                    type: integer
                    default: 0
                    maximum: 100
                    minimum: 0
              tags:
                description: An optional set of strings associated with the Upstream for
                  grouping and filtering.
                type: array
                items:
                  type: string
                example:
                  - user-level
                  - low-priority
              host_header:
                description: The hostname to be used as Host header when proxying requests
                  through Kong.
                type: string
              client_certificate:
                description: If set, the certificate to be used as client certificate while TLS
                  handshaking to the upstream server.
                type: object
                properties:
                  id:
                    type: string
                    example: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6
            required:
              - name
            x-examples:
              Example 1:
                id: 58c8ccbb-eafb-4566-991f-2ed4f678fa70
                created_at: 1422386534
                name: my-upstream
                algorithm: round-robin
                hash_on: none
                hash_fallback: none
                hash_on_cookie_path: /
                slots: 10000
                healthchecks:
                  passive:
                    type: http
                    healthy:
                      http_statuses:
                        - 200
                        - 201
                        - 202
                        - 203
                        - 204
                        - 205
                        - 206
                        - 207
                        - 208
                        - 226
                        - 300
                        - 301
                        - 302
                        - 303
                        - 304
                        - 305
                        - 306
                        - 307
                        - 308
                      successes: 0
                    unhealthy:
                      http_statuses:
                        - 429
                        - 500
                        - 503
                      timeouts: 0
                      http_failures: 0
                      tcp_failures: 0
                  active:
                    https_verify_certificate: true
                    healthy:
                      http_statuses:
                        - 200
                        - 302
                      successes: 0
                      interval: 0
                    unhealthy:
                      http_failures: 0
                      http_statuses:
                        - 429
                        - 404
                        - 500
                        - 501
                        - 502
                        - 503
                        - 504
                        - 505
                      timeouts: 0
                      tcp_failures: 0
                      interval: 0
                    type: http
                    concurrency: 10
                    headers:
                      - x-my-header:
                          - foo
                          - bar
                        x-another-header:
                          - bla
                    timeout: 1
                    http_path: /
                    https_sni: example.com
                  threshold: 0
                tags:
                  - user-level
                  - low-priority
                host_header: example.com
                client_certificate:
                  id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6
                use_srv_name: false
          examples:
            Upstream:
              value:
                name: my-upstream
                algorithm: round-robin
                hash_on: none
                hash_fallback: none
                hash_on_cookie_path: /
                slots: 10000
                healthchecks:
                  passive:
                    type: http
                    healthy:
                      http_statuses:
                        - 200
                        - 201
                        - 202
                        - 203
                        - 204
                        - 205
                        - 206
                        - 207
                        - 208
                        - 226
                        - 300
                        - 301
                        - 302
                        - 303
                        - 304
                        - 305
                        - 306
                        - 307
                        - 308
                      successes: 0
                    unhealthy:
                      http_statuses:
                        - 429
                        - 500
                        - 503
                      timeouts: 0
                      http_failures: 0
                      tcp_failures: 0
                  active:
                    https_verify_certificate: true
                    healthy:
                      http_statuses:
                        - 200
                        - 302
                      successes: 0
                      interval: 0
                    unhealthy:
                      http_failures: 0
                      http_statuses:
                        - 429
                        - 404
                        - 500
                        - 501
                        - 502
                        - 503
                        - 504
                        - 505
                      timeouts: 0
                      tcp_failures: 0
                      interval: 0
                    type: http
                    concurrency: 10
                    headers:
                      type: object
                      properties:
                        x-my-header:
                          description: The value(s) of the x-my-header header.
                          type: array
                          items:
                            type: string
                        x-another-header:
                          description: The value(s) of the x-another-header header.
                          type: array
                          items:
                            type: string
                    timeout: 1
                    http_path: /
                    https_sni: example.com
                  threshold: 0
                tags:
                  - user-level
                  - low-priority
                host_header: example.com
                client_certificate:
                  id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6
                use_srv_name: false
            Example request:
              value:
                name: my-upstream
                tags:
                  - user-level
                  - low-priority
                algorithm: round-robin
  schemas:
    Upstream:
      description: The upstream object represents a virtual hostname and can be used
        to loadbalance incoming requests over multiple services (targets). So
        for example an upstream named `service.v1.xyz` for a service object
        whose `host` is `service.v1.xyz`. Requests for this service would be
        proxied to the targets defined within the upstream. An upstream also
        includes a [health checker][healthchecks], which is able to enable and
        disable targets based on their ability or inability to serve requests.
        The configuration for the health checker is stored in the upstream
        object, and applies to all of its targets.
      type: object
      properties:
        algorithm:
          description: Which load balancing algorithm to use.
          type: string
          default: round-robin
        client_certificate:
          description: If set, the certificate to be used as client certificate while TLS
            handshaking to the upstream server.
          type: object
          additionalProperties: false
          properties:
            id:
              type: string
        created_at:
          description: Unix epoch when the resource was created.
          type: integer
          example: 1422386534
        updated_at:
          description: Unix epoch when the resouce was updated.
          type: integer
          example: 1422386534
        hash_fallback:
          description: What to use as hashing input if the primary `hash_on` does not
            return a hash (eg. header is missing, or no Consumer identified).
            Not available if `hash_on` is set to `cookie`.
          type: string
          default: none
        hash_fallback_header:
          description: The header name to take the value from as hash input. Only required
            when `hash_fallback` is set to `header`.
          type: string
        hash_fallback_query_arg:
          description: The name of the query string argument to take the value from as
            hash input. Only required when `hash_fallback` is set to
            `query_arg`.
          type: string
        hash_fallback_uri_capture:
          description: The name of the route URI capture to take the value from as hash
            input. Only required when `hash_fallback` is set to `uri_capture`.
          type: string
        hash_on:
          description: What to use as hashing input. Using `none` results in a
            weighted-round-robin scheme with no hashing.
          type: string
          default: none
        hash_on_cookie:
          description: The cookie name to take the value from as hash input. Only required
            when `hash_on` or `hash_fallback` is set to `cookie`. If the
            specified cookie is not in the request, Kong will generate a value
            and set the cookie in the response.
          type: string
        hash_on_cookie_path:
          description: The cookie path to set in the response headers. Only required when
            `hash_on` or `hash_fallback` is set to `cookie`.
          type: string
          default: /
        hash_on_header:
          description: The header name to take the value from as hash input. Only required
            when `hash_on` is set to `header`.
          type: string
        hash_on_query_arg:
          description: The name of the query string argument to take the value from as
            hash input. Only required when `hash_on` is set to `query_arg`.
          type: string
        hash_on_uri_capture:
          description: The name of the route URI capture to take the value from as hash
            input. Only required when `hash_on` is set to `uri_capture`.
          type: string
        healthchecks:
          type: object
          properties:
            active:
              type: object
              properties:
                concurrency:
                  type: integer
                  default: 10
                headers:
                  type: object
                healthy:
                  type: object
                  properties:
                    http_statuses:
                      type: array
                      items:
                        type: integer
                      default:
                        - 200
                        - 302
                    interval:
                      type: number
                      default: 0
                    successes:
                      type: integer
                      default: 0
                http_path:
                  type: string
                  default: /
                https_sni:
                  type: string
                https_verify_certificate:
                  type: boolean
                  default: true
                timeout:
                  type: number
                  default: 1
                type:
                  type: string
                  default: http
                unhealthy:
                  type: object
                  properties:
                    http_failures:
                      type: integer
                      default: 0
                    http_statuses:
                      type: array
                      items:
                        type: integer
                      default:
                        - 429
                        - 404
                        - 500
                        - 501
                        - 502
                        - 503
                        - 504
                        - 505
                    interval:
                      type: number
                      default: 0
                    tcp_failures:
                      type: integer
                      default: 0
                    timeouts:
                      type: integer
                      default: 0
            passive:
              type: object
              properties:
                healthy:
                  type: object
                  properties:
                    http_statuses:
                      type: array
                      items:
                        type: integer
                      default:
                        - 200
                        - 201
                        - 202
                        - 203
                        - 204
                        - 205
                        - 206
                        - 207
                        - 208
                        - 226
                        - 300
                        - 301
                        - 302
                        - 303
                        - 304
                        - 305
                        - 306
                        - 307
                        - 308
                    successes:
                      type: integer
                      default: 0
                type:
                  type: string
                  default: http
                unhealthy:
                  type: object
                  properties:
                    http_failures:
                      type: integer
                      default: 0
                    http_statuses:
                      type: array
                      items:
                        type: integer
                      default:
                        - 429
                        - 500
                        - 503
                    tcp_failures:
                      type: integer
                      default: 0
                    timeouts:
                      type: integer
                      default: 0
            threshold:
              type: number
              default: 0
        host_header:
          description: The hostname to be used as `Host` header when proxying requests
            through Kong.
          type: string
        id:
          type: string
        name:
          description: This is a hostname, which must be equal to the `host` of a service.
          type: string
        slots:
          description: The number of slots in the load balancer algorithm. If `algorithm`
            is set to `round-robin`, this setting determines the maximum number
            of slots. If `algorithm` is set to `consistent-hashing`, this
            setting determines the actual number of slots in the algorithm.
            Accepts an integer in the range `10`-`65536`.
          type: integer
          default: 10000
        tags:
          description: An optional set of strings associated with the Upstream for
            grouping and filtering.
          type: array
          items:
            type: string
        use_srv_name:
          description: If set, the balancer will use SRV hostname(if DNS Answer has SRV
            record) as the proxy upstream `Host`.
          type: boolean
          default: false
      example:
        algorithm: round-robin
        hash_fallback: none
        hash_on: none
        hash_on_cookie_path: /
        healthchecks:
          active:
            concurrency: 10
            healthy:
              http_statuses:
                - 200
                - 302
              interval: 0
              successes: 0
            http_path: /
            https_verify_certificate: true
            timeout: 1
            type: http
            unhealthy:
              http_failures: 0
              http_statuses:
                - 429
                - 404
                - 500
                - 501
                - 502
                - 503
                - 504
                - 505
              interval: 0
              tcp_failures: 0
              timeouts: 0
          passive:
            healthy:
              http_statuses:
                - 200
                - 201
                - 202
                - 203
                - 204
                - 205
                - 206
                - 207
                - 208
                - 226
                - 300
                - 301
                - 302
                - 303
                - 304
                - 305
                - 306
                - 307
                - 308
              successes: 0
            type: http
            unhealthy:
              http_failures: 0
              http_statuses:
                - 429
                - 500
                - 503
              tcp_failures: 0
              timeouts: 0
          threshold: 0
        id: 6eed5e9c-5398-4026-9a4c-d48f18a2431e
        name: api.example.internal
        slots: 10000
  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.
```
