Update a Global Rule (Partial)

PATCH /apisix/admin/global_rules/{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 GlobalRule. Object fields are merged recursively; arrays are replaced.

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

id?||||

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

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/global_rules/my-resource-1?ttl=3600" \  -H "Content-Type: application/json" \  -d '{    "plugins": {      "serverless-pre-function": {        "phase": "rewrite",        "functions": [          "return function() end"        ]      }    }  }'

Successful response.

{
  "key": "/apisix/global_rules/1",
  "value": {
    "plugins": {
      "limit-count": {
        "rejected_code": 503,
        "time_window": 60,
        "key": "remote_addr",
        "key_type": "var",
        "count": 3,
        "allow_degradation": false,
        "show_limit_quota_header": true,
        "policy": "local"
      }
    },
    "update_time": 1684376614,
    "create_time": 1684375502,
    "id": "1"
  }
}

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

Update a Global Rule (Partial)

Partially update a global rule'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 GlobalRule. 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
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): Global Rule configuration. Global plugins apply independently of locally bound plugins. For HTTP requests, execution is interleaved by phase: global rewrite, local rewrite, global access, then local access. Priorities order plugins within each phase and scope, and an early response skips handlers scheduled later.
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.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/global_rules/{id}'

Update a Global Rule (Partial)

200application/json

400application/json

401application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`