v61

latestOpenAPI 3.1.0Apache 2.0raw.githubusercontent.com2026-08-018131,3812.6 MB

Plugins

Upsert a Plugin

Create or Update Plugin using ID.

put/v2/control-planes/{controlPlaneId}/core-entities/plugins/{PluginId}

Request body

conditionstring nullable

An expression used for conditional control over plugin execution. If the expression evaluates to true during the request flow, the plugin is executed; otherwise, it is skipped.

configobject nullable

The configuration properties for the Plugin which can be found on the plugins documentation page in the Kong Hub.

created_atinteger nullable

Unix epoch when the resource was created.

enabledboolean nullable

Whether the plugin is applied.

idstring nullable

A string representing a UUID (universally unique identifier).

instance_namestring nullable

A unique string representing a UTF-8 encoded name.

namestring required

The name of the Plugin that's going to be added. Currently, the Plugin must be installed in every Kong instance separately.

protocolsstring[] nullable

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".

tagsstring[] nullable

An optional set of strings associated with the Plugin for grouping and filtering.

updated_atinteger nullable

Unix epoch when the resource was last updated.

Example request

{
  "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",
  "partials": [
    {
      "id": "cff1230a-00f7-4ae8-b376-c370f0eb4dae",
      "name": "foo-partial",
      "path": "config.redis"
    },
    {
      "id": "129ee345-cba8-4e55-9d6d-93c223ff91ae",
      "name": "bar-partial",
      "path": "config.redis"
    }
  ],
  "protocols": [
    "grpc",
    "grpcs",
    "http",
    "https"
  ]
}

Response

Successfully upserted Plugin