Kong Upstreams API

openapi: 3.2.0
info:
  title: Kong Upstreams API
  version: 3.14.0
  contact:
    email: support@konghq.com
    name: Kong Inc
    url: https://konghq.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-refined-note:
  - x-extensions-note differs across the merged source definitions and was not carried
  - x-oas-source differs across the merged source definitions and was not carried
  - x-oas-source-link differs across the merged source definitions and was not carried
  description: 'Operations tagged Upstreams across 2 of this provider''s published API definitions: kong-gateway-admin-api.yml, kong-konnect-platform-api.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: Default Admin API URL
  url: '{protocol}://{hostname}:{port}{path}'
  variables:
    hostname:
      default: localhost
      description: Hostname for Kong's Admin API
    path:
      default: /
      description: Base path for Kong's Admin API
    port:
      default: '8001'
      description: Port for Kong's Admin API
    protocol:
      default: http
      description: Protocol for requests to Kong's Admin API
      enum:
      - http
      - https
- url: https://global.api.konghq.com
- url: https://us.api.konghq.com
- url: https://eu.api.konghq.com
- url: https://au.api.konghq.com
tags:
- description: 'The upstream object represents a virtual hostname and can be used to load balance incoming requests over multiple services (targets).

    <br><br>

    An upstream also includes a [health checker](https://developer.konghq.com/gateway/traffic-control/health-checks-circuit-breakers/), which can 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.'
  name: Upstreams
paths:
  /{workspace}/upstreams:
    post:
      x-speakeasy-entity-operation:
        terraform-datasource: null
        terraform-resource: Upstream#create
      operationId: create-upstream
      summary: Create a new Upstream
      description: Create a new Upstream
      parameters:
      - $ref: '#/components/parameters/Workspace'
      requestBody:
        description: Description of the new Upstream for creation
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Upstream'
      responses:
        '201':
          description: Successfully created Upstream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upstream'
        '401':
          $ref: '#/components/responses/HTTP401Error'
      tags:
      - Upstreams
      security:
      - adminToken: []
    servers:
    - description: Default Admin API URL
      url: '{protocol}://{hostname}:{port}{path}'
      variables:
        hostname:
          default: localhost
          description: Hostname for Kong's Admin API
        path:
          default: /
          description: Base path for Kong's Admin API
        port:
          default: '8001'
          description: Port for Kong's Admin API
        protocol:
          default: http
          description: Protocol for requests to Kong's Admin API
          enum:
          - http
          - https
  /{workspace}/upstreams/{UpstreamIdOrName}:
    parameters:
    - $ref: '#/components/parameters/UpstreamIdOrName'
    delete:
      x-speakeasy-entity-operation:
        terraform-datasource: null
        terraform-resource: Upstream#delete
      operationId: delete-upstream
      summary: Delete an Upstream
      description: Delete an Upstream
      parameters:
      - $ref: '#/components/parameters/UpstreamIdOrName'
      - $ref: '#/components/parameters/Workspace'
      responses:
        '204':
          description: Successfully deleted Upstream or the resource didn't exist
        '401':
          $ref: '#/components/responses/HTTP401Error'
      tags:
      - Upstreams
      security:
      - adminToken: []
    get:
      x-speakeasy-entity-operation:
        terraform-datasource: null
        terraform-resource: Upstream#read
      operationId: get-upstream
      summary: Get an Upstream
      description: Get an Upstream using ID or name.
      parameters:
      - $ref: '#/components/parameters/Workspace'
      responses:
        '200':
          description: Successfully fetched Upstream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upstream'
        '401':
          $ref: '#/components/responses/HTTP401Error'
        '404':
          description: Resource does not exist
      tags:
      - Upstreams
      security:
      - adminToken: []
    put:
      x-speakeasy-entity-operation:
        terraform-datasource: null
        terraform-resource: Upstream#update
      operationId: upsert-upstream
      summary: Upsert a Upstream
      description: Create or Update Upstream using ID or name.
      parameters:
      - $ref: '#/components/parameters/Workspace'
      requestBody:
        description: Description of the Upstream
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Upstream'
      responses:
        '200':
          description: Successfully upserted Upstream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upstream'
        '401':
          $ref: '#/components/responses/HTTP401Error'
      tags:
      - Upstreams
      security:
      - adminToken: []
    servers:
    - description: Default Admin API URL
      url: '{protocol}://{hostname}:{port}{path}'
      variables:
        hostname:
          default: localhost
          description: Hostname for Kong's Admin API
        path:
          default: /
          description: Base path for Kong's Admin API
        port:
          default: '8001'
          description: Port for Kong's Admin API
        protocol:
          default: http
          description: Protocol for requests to Kong's Admin API
          enum:
          - http
          - https
  /v2/control-planes/{controlPlaneId}/core-entities/upstreams:
    parameters:
    - $ref: '#/components/parameters/controlPlaneId'
    get:
      operationId: list-upstream
      summary: List all Upstreams
      description: List all Upstreams
      parameters:
      - $ref: '#/components/parameters/PaginationSize'
      - $ref: '#/components/parameters/PaginationOffset'
      - $ref: '#/components/parameters/PaginationTagsFilter'
      responses:
        '200':
          description: A successful response listing Upstreams
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Upstream_2'
                  next:
                    $ref: '#/components/schemas/PaginationNextResponse'
                  offset:
                    $ref: '#/components/schemas/PaginationOffsetResponse'
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
      tags:
      - Upstreams
      security:
      - personalAccessToken: []
      - systemAccountAccessToken: []
      - konnectAccessToken: []
      - serviceAccessToken: []
    post:
      operationId: create-upstream
      summary: Create a new Upstream
      description: Create a new Upstream
      requestBody:
        description: Description of the new Upstream for creation
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Upstream_2'
      responses:
        '201':
          description: Successfully created Upstream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upstream_2'
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
      tags:
      - Upstreams
      security:
      - personalAccessToken: []
      - systemAccountAccessToken: []
      - konnectAccessToken: []
      - serviceAccessToken: []
    servers:
    - url: https://global.api.konghq.com
    - url: https://us.api.konghq.com
    - url: https://eu.api.konghq.com
    - url: https://au.api.konghq.com
  /v2/control-planes/{controlPlaneId}/core-entities/upstreams/{UpstreamId}:
    parameters:
    - $ref: '#/components/parameters/UpstreamId'
    - $ref: '#/components/parameters/controlPlaneId'
    delete:
      operationId: delete-upstream
      summary: Delete an Upstream
      description: Delete an Upstream
      parameters:
      - $ref: '#/components/parameters/UpstreamId'
      responses:
        '204':
          description: Successfully deleted Upstream or the resource didn't exist
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
      tags:
      - Upstreams
      security:
      - personalAccessToken: []
      - systemAccountAccessToken: []
      - konnectAccessToken: []
      - serviceAccessToken: []
    get:
      operationId: get-upstream
      summary: Get an Upstream
      description: Get an Upstream using ID or name.
      responses:
        '200':
          description: Successfully fetched Upstream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upstream_2'
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
        '404':
          description: Resource does not exist
      tags:
      - Upstreams
      security:
      - personalAccessToken: []
      - systemAccountAccessToken: []
      - konnectAccessToken: []
      - serviceAccessToken: []
    put:
      operationId: upsert-upstream
      summary: Upsert a Upstream
      description: Create or Update Upstream using ID or name.
      requestBody:
        description: Description of the Upstream
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Upstream_2'
      responses:
        '200':
          description: Successfully upserted Upstream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upstream_2'
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
      tags:
      - Upstreams
      security:
      - personalAccessToken: []
      - systemAccountAccessToken: []
      - konnectAccessToken: []
      - serviceAccessToken: []
    servers:
    - url: https://global.api.konghq.com
    - url: https://us.api.konghq.com
    - url: https://eu.api.konghq.com
    - url: https://au.api.konghq.com
components:
  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'
    HTTP401Error_2:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayUnauthorizedError'
  schemas:
    Upstream:
      x-speakeasy-entity: 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
          enum:
          - consistent-hashing
          - latency
          - least-connections
          - round-robin
          - sticky-sessions
          nullable: true
        client_certificate:
          description: If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.
          type: object
          nullable: true
          properties:
            id:
              type: string
          x-foreign: true
        created_at:
          description: Unix epoch when the resource was created.
          type: integer
          nullable: true
        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
          enum:
          - consumer
          - cookie
          - header
          - ip
          - none
          - path
          - query_arg
          - uri_capture
          nullable: true
        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
          nullable: true
        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
          minLength: 1
          nullable: true
        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
          minLength: 1
          nullable: true
        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:
          - consumer
          - cookie
          - header
          - ip
          - none
          - path
          - query_arg
          - uri_capture
          nullable: true
        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
          nullable: true
        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: /
          nullable: true
        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
          nullable: true
        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
          minLength: 1
          nullable: true
        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
          minLength: 1
          nullable: true
        healthchecks:
          description: The array of healthchecks.
          type: object
          default:
            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
          nullable: true
          properties:
            active:
              type: object
              default:
                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
              properties:
                concurrency:
                  type: integer
                  default: 10
                  maximum: 2147483648
                  minimum: 1
                headers:
                  description: A map of header names to arrays of header values.
                  type: object
                  additionalProperties:
                    items:
                      type: string
                    type: array
                healthy:
                  type: object
                  default:
                    http_statuses:
                    - 200
                    - 302
                    interval: 0
                    successes: 0
                  properties:
                    http_statuses:
                      type: array
                      items:
                        maximum: 999
                        minimum: 100
                        type: integer
                      default:
                      - 200
                      - 302
                    interval:
                      type: number
                      default: 0
                      maximum: 65535
                      minimum: 0
                    successes:
                      type: integer
                      default: 0
                      maximum: 255
                      minimum: 0
                http_path:
                  description: A string representing a URL path, such as /path/to/resource. Must start with a forward slash (/) and must not contain empty segments (i.e., two consecutive forward slashes).
                  type: string
                  default: /
                https_sni:
                  description: A string representing an SNI (server name indication) value for TLS.
                  type: string
                https_verify_certificate:
                  type: boolean
                  default: true
                timeout:
                  type: number
                  default: 1
                  maximum: 65535
                  minimum: 0
                type:
                  type: string
                  default: http
                  enum:
                  - grpc
                  - grpcs
                  - http
                  - https
                  - tcp
                unhealthy:
                  type: object
                  default:
                    http_failures: 0
                    http_statuses:
                    - 429
                    - 404
                    - 500
                    - 501
                    - 502
                    - 503
                    - 504
                    - 505
                    interval: 0
                    tcp_failures: 0
                    timeouts: 0
                  properties:
                    http_failures:
                      type: integer
                      default: 0
                      maximum: 255
                      minimum: 0
                    http_statuses:
                      type: array
                      items:
                        maximum: 999
                        minimum: 100
                        type: integer
                      default:
                      - 429
                      - 404
                      - 500
                      - 501
                      - 502
                      - 503
                      - 504
                      - 505
                    interval:
                      type: number
                      default: 0
                      maximum: 65535
                      minimum: 0
                    tcp_failures:
                      type: integer
                      default: 0
                      maximum: 255
                      minimum: 0
                    timeouts:
                      type: integer
                      default: 0
                      maximum: 255
                      minimum: 0
            passive:
              type: object
              default:
                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
              properties:
                healthy:
                  type: object
                  default:
                    http_statuses:
                    - 200
                    - 201
                    - 202
                    - 203
                    - 204
                    - 205
                    - 206
                    - 207
                    - 208
                    - 226
                    - 300
                    - 301
                    - 302
                    - 303
                    - 304
                    - 305
                    - 306
                    - 307
                    - 308
                    successes: 0
                  properties:
                    http_statuses:
                      type: array
                      items:
                        maximum: 999
                        minimum: 100
                        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
                      maximum: 255
                      minimum: 0
                type:
                  type: string
                  default: http
                  enum:
                  - grpc
                  - grpcs
                  - http
                  - https
                  - tcp
                unhealthy:
                  type: object
                  default:
                    http_failures: 0
                    http_statuses:
                    - 429
                    - 500
                    - 503
                    tcp_failures: 0
                    timeouts: 0
                  properties:
                    http_failures:
                      type: integer
                      default: 0
                      maximum: 255
                      minimum: 0
                    http_statuses:
                      type: array
                      items:
                        maximum: 999
                        minimum: 100
                        type: integer
                      default:
                      - 429
                      - 500
                      - 503
                    tcp_failures:
                      type: integer
                      default: 0
                      maximum: 255
                      minimum: 0
                    timeouts:
                      type: integer
                      default: 0
                      maximum: 255
                      minimum: 0
            threshold:
              type: number
              default: 0
              maximum: 100
              minimum: 0
        host_header:
          description: The hostname to be used as `Host` header when proxying requests through Kong.
          type: string
          nullable: true
        id:
          description: A string representing a UUID (universally unique identifier).
          type: string
          nullable: true
        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
          maximum: 65536
          minimum: 10
          nullable: true
        sticky_sessions_cookie:
          description: The cookie name to keep sticky sessions.
          type: string
          nullable: true
        sticky_sessions_cookie_path:
          description: A string representing a URL path, such as /path/to/resource. Must start with a forward slash (/) and must not contain empty segments (i.e., two consecutive forward slashes).
          type: string
          default: /
          nullable: true
        tags:
          description: An optional set of strings associated with the Upstream 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
        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
          nullable: true
      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
      additionalProperties: false
      required:
      - name
    GatewayUnauthorizedError:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
      required:
      - message
      - status
    PaginationNextResponse:
      description: URI to the next page (may be null)
      type: string
    PaginationOffsetResponse:
      description: Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page
      type: string
    Upstream_2:
      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
          enum:
          - consistent-hashing
          - latency
          - least-connections
          - round-robin
          - sticky-sessions
          nullable: true
          x-speakeasy-unknown-values: allow
        client_certificate:
          description: If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.
          type: object
          nullable: true
          properties:
            id:
              type: string
          x-foreign: true
        created_at:
          description: Unix epoch when the resource was created.
          type: integer
          nullable: true
        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
          enum:
          - consumer
          - cookie
          - header
          - ip
          - none
          - path
          - query_arg
          - uri_capture
          nullable: true
          x-speakeasy-unknown-values: allow
        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
          nullable: true
        hash_fallback_query_arg:
          description: The name of the query string argume

# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kong/refs/heads/main/openapi/kong-upstreams-api-openapi.yml