Create or Replace a Consumer Group

PUT /apisix/admin/consumer_groups/{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

ConsumerGroup configuration body for create / replace / patch.

Consumer Group configuration. Defines shared plugin configurations for multiple consumers.

id?|

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

name?string

Human-readable name.

Length1 <= length <= 256

desc?string

Description of this group.

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 PUT "http://127.0.0.1:9180/apisix/admin/consumer_groups/my-resource-1?ttl=3600" \  -H "Content-Type: application/json" \  -d '{    "plugins": {      "limit-count": {        "count": 200,        "time_window": 60,        "rejected_code": 429,        "key_type": "var",        "key": "consumer_name"      }    }  }'

Created

{
  "key": "/apisix/consumer_groups/company_a",
  "value": {
    "plugins": {
      "limit-count": {
        "allow_degradation": false,
        "count": 2,
        "group": "company_a",
        "time_window": 60,
        "key": "remote_addr",
        "key_type": "var",
        "show_limit_quota_header": true,
        "rejected_code": 503,
        "policy": "local"
      }
    },
    "desc": "desc",
    "id": "company_a",
    "create_time": 1684377809,
    "update_time": 1684378459
  }
}

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/consumer_groups/{id}

Create or Replace a Consumer Group

Create a new consumer group with a specified ID, or fully replace an existing one.

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

ConsumerGroup configuration body for create / replace / patch.

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
name (string, optional): Human-readable name.
desc (string, optional): Description of this group.
labels (object, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
create_time (integer, optional): Unix timestamp of creation. Read-only.
update_time (integer, optional): Unix timestamp of last update. Read-only.
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.

Responses

201: Created
key (string, required):
value (object, required): Consumer Group configuration. Defines shared plugin configurations for multiple consumers.
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 of this group.
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.

cURL

curl -X PUT 'http://127.0.0.1:9180/apisix/admin/consumer_groups/{id}'

Create or Replace a Consumer Group

201application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`