Update a Consumer Group (Partial)

PATCH /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

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

Partial update for an existing ConsumerGroup. 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 ConsumerGroup schema.

id?||||

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

name?|

Human-readable name.

Length1 <= length <= 256

desc?|

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 PATCH "http://127.0.0.1:9180/apisix/admin/consumer_groups/my-resource-1?ttl=3600" \  -H "Content-Type: application/json" \  -d '{    "desc": "Updated consumer group description"  }'

Successful response.

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

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

Update a Consumer Group (Partial)

Partially update a consumer group'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 ConsumerGroup. 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 of this group.
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): 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.
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/consumer_groups/{id}'

Update a Consumer Group (Partial)

200application/json

400application/json

401application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`