---
title: "Upsert a Plugin"
url: "https://nov18-dev.movespot.fyi/apis/konnect-runtime-groups-configuration-0/versions/af18902c-58f1-49d7-8ec2-9987b4e0d1bd/operations/upsert-plugin"
---

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

# Upsert a Plugin

`PUT` `/runtime-groups/{runtimeGroupId}/core-entities/plugins/{plugin_id_or_instance_name}`

Operation ID: `upsert-plugin`

Create or Update Plugin using ID.

## Path parameters

- `plugin_id_or_instance_name` (string, required) - The unique identifier of the Plugin to create or update.
- `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 upserted Plugin
- `400` - Invalid Plugin

## 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/plugins/{plugin_id_or_instance_name}:
    parameters:
      - $ref: "#/components/parameters/plugin_id_or_instance_name"
      - $ref: "#/components/parameters/runtimeGroupId"
    put:
      operationId: upsert-plugin
      summary: Upsert a Plugin
      description: Create or Update Plugin using ID.
      requestBody:
        $ref: "#/components/requestBodies/plugin-request"
      responses:
        "200":
          description: Successfully upserted Plugin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Plugin"
              examples:
                example:
                  value:
                    config:
                      anonymous: null
                      hide_credentials: false
                      key_in_body: false
                      key_in_header: true
                      key_in_query: true
                      key_names:
                        - apikey
                      run_on_preflight: true
                    enabled: true
                    id: 3fd1eea1-885a-4011-b986-289943ff8177
                    name: key-auth
                    protocols:
                      - grpc
                      - grpcs
                      - http
                      - https
        "400":
          description: Invalid Plugin
          content:
            application/json:
              schema:
                type: object
      tags:
        - Plugins
security:
  - konnectAccessToken: []
  - personalAccessToken: []
components:
  parameters:
    plugin_id_or_instance_name:
      name: plugin_id_or_instance_name
      in: path
      required: true
      schema:
        type: string
        example: response-ratelimiting
      description: The unique identifier of the Plugin to create or update.
    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:
    plugin-request:
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                description: The name of the Plugin that’s going to be added. Currently, the
                  Plugin must be installed in every Kong instance separately.
                type: string
                example: rate-limiting
                nullable: true
              route:
                description: "If set, the plugin will only activate when receiving requests via
                  the specified route. Leave unset for the plugin to activate
                  regardless of the route being used. Default: `null`.With
                  form-encoded, the notation is `route.id=<route id> or
                  route.name=<route name>`. With JSON, use `route:{id:<route
                  id>}` or `route:{name:<route name>}`."
                type: object
                properties:
                  id:
                    description: The Id of the route.
                    type: string
                    example: a2e013e8-7623-4494-a347-6d29108ff68b
              service:
                description: If set, the plugin will only activate when receiving requests via
                  one of the routes belonging to the specified service.
                type: object
                nullable: true
                properties:
                  id:
                    description: The Id of the route.
                    type: string
                    example: a2e013e8-7623-4494-a347-6d29108ff68b
              instance_name:
                description: |
                  The Plugin instance name.
                type: string
                example: rate-limiting-foo
              config:
                description: The configuration properties for the Plugin
                type: object
                properties:
                  hour:
                    type: integer
                    example: 500
                  minute:
                    type: integer
                    example: 500
              protocols:
                description: A list of the request protocols that will trigger this plugin.
                type: array
                items:
                  type: string
                  enum:
                    - http
                    - grpc
                    - grpcs
                    - tls
                    - tcp
                  default: http
              enabled:
                description: |
                  Whether the plugin is applied. Default: `true`.
                type: boolean
                default: true
              tags:
                description: >
                  An optional set of strings associated with the Plugin for
                  grouping and filtering.
                type: array
                items:
                  type: string
            x-examples:
              Example 1:
                name: rate-limiting
                route: null
                service: null
                consumer: null
                instance_name: rate-limiting-foo
                config:
                  hour: 500
                  minute: 20
                protocols:
                  - http
                  - https
                enabled: true
                tags:
                  - user-level
                  - low-priority
                ordering:
                  before:
                    - plugin-name
          examples:
            request example:
              value:
                name: rate-limiting
                consumer: string
                instance_name: rate-limiting-foo
                config:
                  hour: 500
                  minute: 500
                protocols:
                  - http
                enabled: true
                tags:
                  - string
      description: Plugin request body
  schemas:
    Plugin:
      description: A Plugin entity represents a plugin configuration that will be
        executed during the HTTP request/response lifecycle.
      type: object
      properties:
        config:
          description: The configuration properties for the Plugin which can be found on
            the plugins documentation page in the [Kong
            Hub](https://docs.konghq.com/hub/).
          type: object
        consumer:
          description: If set, the plugin will activate only for requests where the
            specified has been authenticated. (Note that some plugins can not be
            restricted to consumers this way.). Leave unset for the plugin to
            activate regardless of the authenticated Consumer.
          type: object
          additionalProperties: false
          properties:
            id:
              type: string
        created_at:
          description: Unix epoch when the resource was created.
          type: integer
        enabled:
          description: Whether the plugin is applied.
          type: boolean
          default: true
        id:
          type: string
        instance_name:
          type: string
        name:
          description: The name of the Plugin that's going to be added. Currently, the
            Plugin must be installed in every Kong instance separately.
          type: string
        ordering:
          type: object
        protocols:
          description: A list of the request protocols that will trigger this plugin. The
            default value, as well as the possible values allowed on this field,
            may change depending on the plugin type. For example, plugins that
            only work in stream mode will only support `tcp` and `tls`.
          type: array
          items:
            type: string
          default:
            - grpc
            - grpcs
            - http
            - https
        route:
          description: If set, the plugin will only activate when receiving requests via
            the specified route. Leave unset for the plugin to activate
            regardless of the route being used.
          type: object
          additionalProperties: false
          properties:
            id:
              type: string
        service:
          description: If set, the plugin will only activate when receiving requests via
            one of the routes belonging to the specified service. Leave unset
            for the plugin to activate regardless of the service being matched.
          type: object
          additionalProperties: false
          properties:
            id:
              type: string
        tags:
          description: An optional set of strings associated with the Plugin for grouping
            and filtering.
          type: array
          items:
            type: string
      example:
        config:
          anonymous: null
          hide_credentials: false
          key_in_body: false
          key_in_header: true
          key_in_query: true
          key_names:
            - apikey
          run_on_preflight: true
        enabled: true
        id: 3fd1eea1-885a-4011-b986-289943ff8177
        name: key-auth
        protocols:
          - grpc
          - grpcs
          - http
          - https
      title: Plugin
  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.
```
