Create or replace a custom plugin

PUT /api/gateway_groups/{gateway_group_id}/custom_plugins/{custom_plugin_name}

Interactive request editor loads with JavaScript.

Authorization

X-API-KEY<token>

In: header

Path Parameters

gateway_group_id*string

Gateway group ID.

Length1 <= length

custom_plugin_name*string

Custom plugin name, as declared by the plugin code.

Request Body

application/json

catalog?string

Plugin category, such as "Traffic" or "Observability".

description?string

A brief description of the plugin.

documentation_link?string

Link to the plugin's documentation.

author?string

Author of the plugin.

logo?string

The base64-encoded logo image.

source_code*string

The source code for the plugin.

Response Body

`application/json`

curl -X PUT "$API_BASE_URL/api/gateway_groups/86fb9981-d9d2-4555-9df8-91ae92129335/custom_plugins/string" \  -H "Content-Type: application/json" \  -d '{    "source_code": "local core = require(\\"apisix.core\\")\\nlocal ngx = ngx\\n\\nlocal schema = {\\n    type = \\"object\\"\\n}\\n\\nlocal plugin_name = \\"route-id-register\\"\\n\\nlocal _M = {\\n  version = 0.2,\\n  priority = 1,\\n  name = plugin_name,\\n  schema = schema,\\n  scope = \\"global\\",\\n}\\n\\nfunction _M.check_schema(conf)\\n  return core.schema.check(schema, conf);\\nend\\n\\nfunction _M.log(conf, ctx)\\n  if ctx.var.route_id then\\n    ngx.var.route_id = ctx.var.route_id\\n  end\\nend\\n\\nreturn _M\\n"  }'

Successfully retrieved or modified the custom plugin.

{
  "value": {
    "gateway_group_id": "bc1b95c9-b348-4832-acc3-e257d2342df1",
    "name": "route-id-register",
    "version": "0.2",
    "source_code": "local core = require(\"apisix.core\")\nlocal ngx = ngx\n\nlocal schema = {\n    type = \"object\"\n}\n\nlocal plugin_name = \"route-id-register\"\n\nlocal _M = {\n  version = 0.2,\n  priority = 1,\n  name = plugin_name,\n  schema = schema,\n  scope = \"global\",\n}\n\nfunction _M.check_schema(conf)\n  return core.schema.check(schema, conf);\nend\n\nfunction _M.log(conf, ctx)\n  if ctx.var.route_id then\n    ngx.var.route_id = ctx.var.route_id\n  end\nend\n\nreturn _M\n",
    "file": "bG9jYWwgY29yZSA9IHJlcXVpcmUoImFwaXNpeC5jb3JlIikKbG9jYWwgbmd4ID0gbmd4Cgpsb2NhbCBzY2hlbWEgPSB7CiAgICB0eXBlID0gIm9iamVjdCIKfQoKbG9jYWwgcGx1Z2luX25hbWUgPSAicm91dGUtaWQtcmVnaXN0ZXIiCgpsb2NhbCBfTSA9IHsKICB2ZXJzaW9uID0gMC4yLAogIHByaW9yaXR5ID0gMSwKICBuYW1lID0gcGx1Z2luX25hbWUsCiAgc2NoZW1hID0gc2NoZW1hLAogIHNjb3BlID0gImdsb2JhbCIsCn0KCmZ1bmN0aW9uIF9NLmNoZWNrX3NjaGVtYShjb25mKQogIHJldHVybiBjb3JlLnNjaGVtYS5jaGVjayhzY2hlbWEsIGNvbmYpOwplbmQKCmZ1bmN0aW9uIF9NLmxvZyhjb25mLCBjdHgpCiAgaWYgY3R4LnZhci5yb3V0ZV9pZCB0aGVuCiAgICBuZ3gudmFyLnJvdXRlX2lkID0gY3R4LnZhci5yb3V0ZV9pZAogIGVuZAplbmQKCnJldHVybiBfTQo=",
    "package": "string",
    "catalog": "General",
    "description": "This plugin records the matched route’s ID into an Nginx variable ($route_id) for use in logging and monitoring.",
    "documentation_link": "https://docs.api7.ai/hub/route-id-register",
    "author": "plugindev",
    "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=",
    "is_obfuscated": false,
    "created_at": 1742288232,
    "updated_at": 1742288235
  }
}

Complete operation details and schema variants

PUT /api/gateway_groups/{gateway_group_id}/custom_plugins/{custom_plugin_name}

Create or replace a custom plugin

Upload a custom plugin to the gateway group, creating it or replacing the code the group is running under this name. The plugin name declared by the uploaded code must match the name in the path.

Only this gateway group is affected: the same plugin name in another gateway group keeps running its own code, which is what lets a plugin be validated in one environment before it reaches another.

Required IAM Permission: Action gateway:UpdateCustomPlugin, Resource arn:api7:gateway:gatewaygroup/{gateway_group_id}

Parameters

gateway_group_id (path, string, required): Gateway group ID.
custom_plugin_name (path, string, required): Custom plugin name, as declared by the plugin code.

Request body

Content type: application/json

catalog (string, optional): Plugin category, such as "Traffic" or "Observability".
description (string, optional): A brief description of the plugin.
documentation_link (string, optional): Link to the plugin's documentation.
author (string, optional): Author of the plugin.
logo (string, optional): The base64-encoded logo image.
oneOf variant 1: Plugin Source Code
source_code (string, required): The source code for the plugin.
oneOf variant 2: Plugin File
file (string, required): Base64-encoded ZIP archive that contains the plugin package. The archive includes the plugin code and the plugin metadata. A plugin that has dependency files holds $PLUGIN_NAME.lua alongside a $PLUGIN_NAME directory of Lua files.

Responses

200: Successfully retrieved or modified the custom plugin.
allOf variant 1
value (object, optional): The specific resource.
allOf variant 2
value (object, optional):
value.gateway_group_id (string, optional): The gateway group ID.
value.name (string, optional): The name of the plugin.
value.version (string, optional): The version of the plugin.
value.source_code (string, optional): The source code for the plugin.
value.file (string, optional): Base64-encoded ZIP archive that contains the plugin package. The archive includes the plugin code and the plugin metadata. A plugin that has dependency files holds $PLUGIN_NAME.lua alongside a $PLUGIN_NAME directory of Lua files.
value.package (string, optional): Base64-encoded tar.gz holding the plugin entry file and its dependency files, which the data plane loads as one unit. Omitted for a plugin that is a single file.
value.catalog (string, optional): Plugin category, such as "Traffic" or "Observability".
value.description (string, optional): A brief description of the plugin.
value.documentation_link (string, optional): Link to the plugin's documentation.
value.author (string, optional): Author of the plugin.
value.logo (string, optional): The base64-encoded logo image.
value.is_obfuscated (boolean, optional): Whether the custom plugin’s source code is obfuscated into bytecode.
value.created_at (integer, optional): The object created timestamp.
value.updated_at (integer, optional): The object updated timestamp.
400: Invalid arguments. Error details will be provided in the response.

cURL

curl -X PUT '$API_BASE_URL/api/gateway_groups/{gateway_group_id}/custom_plugins/{custom_plugin_name}'

Create or replace a custom plugin

200application/json

400

`application/json`