Update a Plugin Config (Partial)

PATCH /apisix/admin/plugin_configs/{id}

Interactive request editor loads with JavaScript.

Authorization

X-API-KEY<token>

Admin API key configured in config.yaml under deployment.admin.admin_key. You can also pass the key as a query parameter api_key or cookie x_api_key.

In: header

Path Parameters

id*string

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Query Parameters

ttl?integer

Time-to-live in seconds. The resource is automatically removed when it expires.

Range1 <= value

Request Body

application/json

Fields to merge into the existing PluginConfig. Object fields are merged recursively; arrays are replaced.

Partial update for an existing PluginConfig. APISIX recursively merges object fields, replaces arrays, and removes an object field when its value is null. The merged resource is then validated against the complete PluginConfig schema.

id?||||

Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.

name?|

Human-readable name.

desc?|

Description.

Lengthlength <= 256

labels?|

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

plugins?|

Plugin configurations as a JSON object. Each key is a plugin name, and the value is that plugin's configuration object.

Example:

{  "limit-count": {    "count": 100,    "time_window": 60  },  "key-auth": {}}

See the Plugin Hub for available plugins and their schemas.

Response Body

`application/json`

curl -X PATCH "http://127.0.0.1:9180/apisix/admin/plugin_configs/my-resource-1?ttl=3600" \  -H "Content-Type: application/json" \  -d '{    "desc": "Updated plugin config description"  }'

Successful response.

{
  "key": "/apisix/plugin_configs/1",
  "value": {
    "plugins": {
      "limit-count": {
        "rejected_code": 503,
        "time_window": 60,
        "key": "remote_addr",
        "key_type": "var",
        "count": 2,
        "allow_degradation": false,
        "show_limit_quota_header": true,
        "policy": "local"
      },
      "prometheus": {
        "prefer_name": false
      }
    },
    "desc": "desc",
    "id": "1",
    "create_time": 1684380007,
    "update_time": 1684380472
  }
}

Invalid configuration

{
  "error_msg": "invalid configuration: property \"uri\" is required"
}

{
  "error_msg": "invalid request body: unexpected character at line 1 column 2"
}

**Unauthorized** — The API key is missing, invalid, or lacks permission.

{
  "error_msg": "failed to check token",
  "description": "missing apikey"
}

{
  "error_msg": "failed to check token",
  "description": "wrong apikey"
}

{
  "error_msg": "failed to check token",
  "description": "invalid method for role viewer"
}

Key not found

{
  "error_msg": "Key not found"
}

Complete operation details and schema variants

PATCH /apisix/admin/plugin_configs/{id}

Update a Plugin Config (Partial)

Partially update a plugin config's configuration.

Parameters

id (path, string, required): Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.
ttl (query, integer, optional): Time-to-live in seconds. The resource is automatically removed when it expires.

Request body

Fields to merge into the existing PluginConfig. Object fields are merged recursively; arrays are replaced.

Content type: application/json

id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
anyOf variant 1: String ID
anyOf variant 2: Integer ID
anyOf variant 3
name (string,null, optional): Human-readable name.
desc (string,null, optional): Description.
labels (object,null, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
create_time (integer,null, optional): Unix timestamp of creation. Read-only.
update_time (integer,null, optional): Unix timestamp of last update. Read-only.
plugins (object,null, optional): Plugin configurations as a JSON object. Each key is a plugin name, and the value is that plugin's configuration object.

Example:

{
  "limit-count": {
    "count": 100,
    "time_window": 60
  },
  "key-auth": {}
}

See the Plugin Hub for available plugins and their schemas.

Responses

200: Successful response.
key (string, required):
value (object, required): Plugin Config — a reusable set of plugin configurations that can be referenced by multiple routes.
value.id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
anyOf variant 1: String ID
anyOf variant 2: Integer ID
value.name (string, optional): Human-readable name.
value.desc (string, optional): Description.
value.labels (object, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
value.create_time (integer, optional): Unix timestamp of creation. Read-only.
value.update_time (integer, optional): Unix timestamp of last update. Read-only.
value.plugins (object, required): Plugin configurations as a JSON object. Each key is a plugin name, and the value is that plugin's configuration object.

Example:

{
  "limit-count": {
    "count": 100,
    "time_window": 60
  },
  "key-auth": {}
}

See the Plugin Hub for available plugins and their schemas.

createdIndex (integer, optional):
modifiedIndex (integer, optional):
400: Bad Request — The request body is invalid or missing required fields.
error_msg (string, required): Human-readable error message describing what went wrong.
401: Unauthorized — The API key is missing, invalid, or lacks permission.
error_msg (string, required): Authentication error message.
description (string, optional): Detailed reason for the authentication failure.
404: Not Found — The specified resource does not exist.
error_msg (string, required): Error message indicating the resource was not found.

cURL

curl -X PATCH 'http://127.0.0.1:9180/apisix/admin/plugin_configs/{id}'

Update a Plugin Config (Partial)

200application/json

400application/json

401application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`