Create or Replace Plugin Metadata

PUT /apisix/admin/plugin_metadata/{plugin_name}

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

plugin_name*string

Plugin name.

Length1 <= length

Query Parameters

ttl?integer

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

Range1 <= value

Request Body

application/json

Plugin metadata. The body schema is plugin-specific (the plugin's metadata_schema). Fetch via GET /apisix/admin/schema/plugins/{plugin_name}.

[key: string]?any

Response Body

`application/json`

curl -X PUT "http://127.0.0.1:9180/apisix/admin/plugin_metadata/limit-count?ttl=3600" \  -H "Content-Type: application/json" \  -d '{}'

Created

{
  "key": "/apisix/plugin_metadata/syslog",
  "value": {
    "log_format": {
      "host": "$host",
      "@timestamp": "$time_iso8601",
      "client_ip": "$remote_addr"
    }
  }
}

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

Complete operation details and schema variants

PUT /apisix/admin/plugin_metadata/{plugin_name}

Create or Replace Plugin Metadata

Set metadata for a specific plugin. This applies to all instances of the plugin across the cluster.

Parameters

plugin_name (path, string, required): Plugin name.
ttl (query, integer, optional): Time-to-live in seconds. The resource is automatically removed when it expires.

Request body

Plugin metadata. The body schema is plugin-specific (the plugin's metadata_schema). Fetch via GET /apisix/admin/schema/plugins/{plugin_name}.

Content type: application/json

Responses

201: Created
key (string, optional): Unique key identifier for this plugin metadata in the data store.
value (object, optional): Plugin metadata values.
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.

cURL

curl -X PUT 'http://127.0.0.1:9180/apisix/admin/plugin_metadata/{plugin_name}'

Create or Replace Plugin Metadata

201application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`