APISIX Admin API (3.11.0)

Download OpenAPI specification:Download

APISIX Admin API is a RESTful API that allows you to create and manage APISIX resources.

Route

A route defines a path to one or more upstream services.

See Routes for more information.

Get All Routes

Get all configured routes.

Responses

Response samples

200

Content type

application/json

{"total": 1,
"list": [{"createdIndex": 203,
"key": "/apisix/routes/1",
"value": {"remote_addrs": ["127.0.0.1"
],
"desc": "desc",
"name": "route-test",
"priority": 0,
"vars": [["http_user",
"==",
"ios"
]
],
"update_time": 1684490006,
"create_time": 1684490006,
"id": "1",
"plugins": {"limit-count": {"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"allow_degradation": false,
"rejected_code": 503,
"time_window": 60,
"key_type": "var",
"key": "remote_addr"
}
},
"status": 1,
"timeout": {"read": 3,
"connect": 3,
"send": 3
},
"uri": "/ip",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"httpbin.org:80": 1
},
"type": "roundrobin",
"scheme": "http"
},
"methods": ["GET",
"POST"
],
"hosts": ["a.com",
"b.com"
]
},
"modifiedIndex": 203
}
]
}

Create Route

Create a route with an ID generated.

Request Body schema: application/json

Any of

desc	string <= 256 characters
	string or integer
status	integer Default: 1 Enum: 1 0 route status, 1 to enable, 0 to disable
	string or integer
enable_websocket	boolean
	string or integer
methods	Array of strings unique Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE" "PURGE"
hosts	Array of strings non-empty unique
	Array of IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) non-empty unique
filter_func	string >= 10 characters ^function
vars	Array of arrays
name	string [ 1 .. 100 ] characters
	string or integer
	string or integer
host	string
priority	integer Default: 0
	object or object
plugins required	object
	IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) client IP
	object Key-value pairs to specify attributes.
	object
script	string [ 10 .. 102400 ] characters
uri required	string [ 1 .. 4096 ] characters
uris	Array of strings non-empty unique

Responses

Request samples

Payload

Content type

application/json

{"name": "route-name",
"desc": "desc",
"hosts": ["a.com",
"b.com"
],
"methods": ["GET",
"POST"
],
"uri": "/ip",
"upstream": {"type": "roundrobin",
"nodes": {"httpbin.org:80": 1
}
}
}

Response samples

201

Content type

application/json

{"value": {"desc": "desc",
"name": "route-name",
"update_time": 1684490245,
"priority": 0,
"id": "00000000000000000206",
"status": 1,
"create_time": 1684490245,
"uri": "/ip",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"httpbin.org:80": 1
},
"type": "roundrobin",
"scheme": "http"
},
"methods": ["GET",
"POST"
],
"hosts": ["a.com",
"b.com"
]
},
"key": "/apisix/routes/00000000000000000206"
}

Create Route by ID

Create a route with a custom ID.

path Parameters

id

required

string

The route id

Request Body schema: application/json

Any of

desc	string <= 256 characters
	string or integer
status	integer Default: 1 Enum: 1 0 route status, 1 to enable, 0 to disable
	string or integer
enable_websocket	boolean
	string or integer
methods	Array of strings unique Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE" "PURGE"
hosts	Array of strings non-empty unique
	Array of IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) non-empty unique
filter_func	string >= 10 characters ^function
vars	Array of arrays
name	string [ 1 .. 100 ] characters
	string or integer
	string or integer
host	string
priority	integer Default: 0
	object or object
plugins required	object
	IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) client IP
	object Key-value pairs to specify attributes.
	object
script	string [ 10 .. 102400 ] characters
uri required	string [ 1 .. 4096 ] characters
uris	Array of strings non-empty unique

Responses

Request samples

Payload

Content type

application/json

{"name": "route-test",
"desc": "desc",
"uri": "/ip",
"hosts": ["a.com",
"b.com"
],
"methods": ["GET",
"POST"
],
"plugins": {"limit-count": {"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr"
}
},
"priority": 0,
"remote_addrs": ["127.0.0.1"
],
"vars": [["http_user",
"==",
"ios"
]
],
"upstream": {"type": "roundrobin",
"nodes": {"httpbin.org:80": 1
}
},
"timeout": {"connect": 3,
"send": 3,
"read": 3
}
}

Response samples

201

Content type

application/json

{"value": {"remote_addrs": ["127.0.0.1"
],
"desc": "desc",
"name": "route-test",
"priority": 0,
"plugins": {"limit-count": {"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"key": "remote_addr",
"rejected_code": 503,
"time_window": 60,
"key_type": "var",
"allow_degradation": false
}
},
"vars": [["http_user",
"==",
"ios"
]
],
"id": "1",
"status": 1,
"uri": "/ip",
"timeout": {"connect": 3,
"read": 3,
"send": 3
},
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"httpbin.org:80": 1
},
"type": "roundrobin",
"scheme": "http"
},
"methods": ["GET",
"POST"
],
"hosts": ["a.com",
"b.com"
]
},
"key": "/apisix/routes/1"
}

Get Route by ID

Get a route by ID.

path Parameters

id

required

string

The route id

Responses

Response samples

200

Content type

application/json

{"createdIndex": 203,
"key": "/apisix/routes/1",
"value": {"remote_addrs": ["127.0.0.1"
],
"desc": "desc",
"name": "route-test",
"priority": 0,
"vars": [["http_user",
"==",
"ios"
]
],
"update_time": 1684490006,
"create_time": 1684490006,
"id": "1",
"plugins": {"limit-count": {"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"allow_degradation": false,
"rejected_code": 503,
"time_window": 60,
"key_type": "var",
"key": "remote_addr"
}
},
"status": 1,
"timeout": {"read": 3,
"connect": 3,
"send": 3
},
"uri": "/ip",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"httpbin.org:80": 1
},
"type": "roundrobin",
"scheme": "http"
},
"methods": ["GET",
"POST"
],
"hosts": ["a.com",
"b.com"
]
},
"modifiedIndex": 203
}

Update Route

Update a route.

path Parameters

id

required

string

Example: 1

The target route id

Request Body schema: application/json

Any of

desc	string <= 256 characters
	string or integer
status	integer Default: 1 Enum: 1 0 route status, 1 to enable, 0 to disable
	string or integer
enable_websocket	boolean
	string or integer
methods	Array of strings unique Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE" "PURGE"
hosts	Array of strings non-empty unique
	Array of IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) non-empty unique
filter_func	string >= 10 characters ^function
vars	Array of arrays
name	string [ 1 .. 100 ] characters
	string or integer
	string or integer
host	string
priority	integer Default: 0
	object or object
plugins required	object
	IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) client IP
	object Key-value pairs to specify attributes.
	object
script	string [ 10 .. 102400 ] characters
uri required	string [ 1 .. 4096 ] characters
uris	Array of strings non-empty unique

Responses

Request samples

Payload

Content type

application/json

{"upstream": {"nodes": {"127.0.0.1:1981": 1
}
}
}

Response samples

200

Content type

application/json

Example

Update Upstream Node To The Route

{"value": {"remote_addrs": ["127.0.0.1"
],
"desc": "desc",
"name": "route-test",
"priority": 0,
"vars": [["http_user",
"==",
"ios"
]
],
"update_time": 1684490363,
"create_time": 1684490006,
"id": "1",
"plugins": {"limit-count": {"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"allow_degradation": false,
"rejected_code": 503,
"time_window": 60,
"key_type": "var",
"key": "remote_addr"
}
},
"status": 1,
"timeout": {"read": 3,
"connect": 3,
"send": 3
},
"uri": "/ip",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"httpbin.org:80": 1,
"127.0.0.1:1981": 1
},
"type": "roundrobin",
"scheme": "http"
},
"methods": ["GET",
"POST"
],
"hosts": ["a.com",
"b.com"
]
},
"key": "/apisix/routes/1"
}

Delete Route by ID

Delete a route by ID.

path Parameters

id

required

string

The route id

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"deleted": "1",
"key": "/apisix/routes/1"
}

Upstream

An upstream is a logical abstraction of one or more upstream addresses.

See Upstreams for more information.

Get All Upstreams

Get all configured upstreams.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"timeout": {"send": 15,
"read": 15,
"connect": 15
},
"desc": "desc",
"id": "1",
"create_time": 1684290697,
"retries": 1,
"pass_host": "pass",
"update_time": 1684291419,
"type": "roundrobin",
"name": "upstream-for-test",
"hash_on": "vars",
"nodes": {"httpbin.org:443": 1
},
"scheme": "https"
},
"key": "/apisix/upstreams/1",
"modifiedIndex": 126,
"createdIndex": 121
},
{"value": {"timeout": {"send": 15,
"read": 15,
"connect": 15
},
"desc": "desc",
"id": "2",
"create_time": 1684291436,
"retries": 1,
"pass_host": "pass",
"update_time": 1684291436,
"type": "roundrobin",
"name": "upstream-for-test",
"hash_on": "vars",
"nodes": {"httpbin.org:443": 1
},
"scheme": "https"
},
"key": "/apisix/upstreams/2",
"modifiedIndex": 127,
"createdIndex": 127
}
],
"total": 2
}

Create Upstream

Create an upstream with an ID generated.

Request Body schema: application/json

One of

desc	string <= 256 characters
key	string The key used with `hash_on` when `type` is `chash`. When `hash_on` is set to `header` or `cookie`, `key` is required. When `hash_on` is set to `consumer`, `key` is not required as the consumer name will be used as the key automatically.
retries	integer >= 0
retry_timeout	number >= 0
pass_host	string Default: "pass" Enum: "pass" "node" "rewrite" Configure the host when the request is forwarded to the upstream. `pass` is used to pass the request's host to the upstream without modification. `node` sets the host to the host of the upstream node. `rewrite` sets the host to the value of `upstream_host`.
upstream_host	string
type	string Default: "roundrobin" Enum: "roundrobin" "chash" "ewma" "least_conn" Load balancing algorithm. Support weighted round robin, consistent hashing, exponentially weighted moving average, and least connections algorithms.
	object or object
hash_on	string Default: "vars" Enum: "vars" "header" "cookie" "consumer" "vars_combinations" Type of value to hash on when `type` is `chash`.
name	string [ 1 .. 100 ] characters
scheme	any Default: "http" Enum: "grpc" "grpcs" "http" "https" "tcp" "tls" "udp" "kafka" Protocol to communicate with the upstream.
service_name	string [ 1 .. 256 ] characters
	object
	object
	string or integer
discovery_type	string discovery type
	object Key-value pairs to specify attributes.
	object
required	object or Array of objects
	object

Responses

Request samples

Payload

Content type

application/json

{"name": "upstream-for-test",
"desc": "desc",
"scheme": "http",
"retries": 1,
"type": "roundrobin",
"nodes": {"127.0.0.1:1980": 1
},
"timeout": {"connect": 15,
"send": 15,
"read": 15
}
}

Response samples

201

Content type

application/json

{"key": "/apisix/upstreams/00000000000000000128",
"value": {"timeout": {"send": 15,
"read": 15,
"connect": 15
},
"desc": "desc",
"id": "00000000000000000128",
"create_time": 1684291897,
"retries": 1,
"pass_host": "pass",
"update_time": 1684291897,
"type": "roundrobin",
"name": "upstream-for-test",
"hash_on": "vars",
"nodes": {"127.0.0.1:1980": 1
},
"scheme": "http"
}
}

Update Upstream

Update an upstream.

path Parameters

id

required

string

Specified upstream ID.

Request Body schema: application/json

One of

desc	string <= 256 characters
key	string The key used with `hash_on` when `type` is `chash`. When `hash_on` is set to `header` or `cookie`, `key` is required. When `hash_on` is set to `consumer`, `key` is not required as the consumer name will be used as the key automatically.
retries	integer >= 0
retry_timeout	number >= 0
pass_host	string Default: "pass" Enum: "pass" "node" "rewrite" Configure the host when the request is forwarded to the upstream. `pass` is used to pass the request's host to the upstream without modification. `node` sets the host to the host of the upstream node. `rewrite` sets the host to the value of `upstream_host`.
upstream_host	string
type	string Default: "roundrobin" Enum: "roundrobin" "chash" "ewma" "least_conn" Load balancing algorithm. Support weighted round robin, consistent hashing, exponentially weighted moving average, and least connections algorithms.
	object or object
hash_on	string Default: "vars" Enum: "vars" "header" "cookie" "consumer" "vars_combinations" Type of value to hash on when `type` is `chash`.
name	string [ 1 .. 100 ] characters
scheme	any Default: "http" Enum: "grpc" "grpcs" "http" "https" "tcp" "tls" "udp" "kafka" Protocol to communicate with the upstream.
service_name	string [ 1 .. 256 ] characters
	object
	object
	string or integer
discovery_type	string discovery type
	object Key-value pairs to specify attributes.
	object
required	object or Array of objects
	object

Responses

Request samples

Payload

Content type

application/json

{"nodes": {"127.0.0.1:1981": 1
}
}

Response samples

200

Content type

application/json

Example

Add Node for Upstream

{"key": "/apisix/upstreams/1",
"value": {"timeout": {"send": 15,
"read": 15,
"connect": 15
},
"desc": "desc",
"id": "1",
"create_time": 1684290697,
"retries": 1,
"pass_host": "pass",
"update_time": 1684291001,
"type": "roundrobin",
"name": "upstream-for-test",
"hash_on": "vars",
"nodes": {"127.0.0.1:1981": 1,
"127.0.0.1:1980": 1
},
"scheme": "http"
}
}

Get Upstream by ID

Get an upstream by ID.

path Parameters

id

required

string

Specified upstream ID.

Responses

Response samples

200

Content type

application/json

{"value": {"timeout": {"send": 15,
"read": 15,
"connect": 15
},
"desc": "desc",
"id": "1",
"create_time": 1684290697,
"retries": 1,
"pass_host": "pass",
"update_time": 1684291419,
"type": "roundrobin",
"name": "upstream-for-test",
"hash_on": "vars",
"nodes": {"httpbin.org:443": 1
},
"scheme": "https"
},
"key": "/apisix/upstreams/1",
"modifiedIndex": 126,
"createdIndex": 121
}

Delete Upstream by ID

Delete an upstream by ID.

path Parameters

id

required

string

Specified upstream ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/upstreams/1",
"deleted": "1"
}

Create an Upstream by ID

Create an upstream with a custom ID.

path Parameters

id

required

string

Specified upstream ID.

Request Body schema: application/json

One of

desc	string <= 256 characters
key	string The key used with `hash_on` when `type` is `chash`. When `hash_on` is set to `header` or `cookie`, `key` is required. When `hash_on` is set to `consumer`, `key` is not required as the consumer name will be used as the key automatically.
retries	integer >= 0
retry_timeout	number >= 0
pass_host	string Default: "pass" Enum: "pass" "node" "rewrite" Configure the host when the request is forwarded to the upstream. `pass` is used to pass the request's host to the upstream without modification. `node` sets the host to the host of the upstream node. `rewrite` sets the host to the value of `upstream_host`.
upstream_host	string
type	string Default: "roundrobin" Enum: "roundrobin" "chash" "ewma" "least_conn" Load balancing algorithm. Support weighted round robin, consistent hashing, exponentially weighted moving average, and least connections algorithms.
	object or object
hash_on	string Default: "vars" Enum: "vars" "header" "cookie" "consumer" "vars_combinations" Type of value to hash on when `type` is `chash`.
name	string [ 1 .. 100 ] characters
scheme	any Default: "http" Enum: "grpc" "grpcs" "http" "https" "tcp" "tls" "udp" "kafka" Protocol to communicate with the upstream.
service_name	string [ 1 .. 256 ] characters
	object
	object
	string or integer
discovery_type	string discovery type
	object Key-value pairs to specify attributes.
	object
required	object or Array of objects
	object

Responses

Request samples

Payload

Content type

application/json

{"name": "upstream-for-test",
"desc": "desc",
"scheme": "http",
"retries": 1,
"type": "roundrobin",
"nodes": {"127.0.0.1:1980": 1
},
"timeout": {"connect": 15,
"send": 15,
"read": 15
}
}

Response samples

201

Content type

application/json

Example

Create an Upstream by ID

{"key": "/apisix/upstreams/1",
"value": {"timeout": {"send": 15,
"read": 15,
"connect": 15
},
"desc": "desc",
"id": "1",
"create_time": 1684290697,
"retries": 1,
"pass_host": "pass",
"update_time": 1684290697,
"type": "roundrobin",
"name": "upstream-for-test",
"hash_on": "vars",
"nodes": {"127.0.0.1:1980": 1
},
"scheme": "http"
}
}

Service

A service is a backend application providing a set of functionalities.

See Services for more information.

Get All Services

Get all configured services.

Responses

Response samples

200

Content type

application/json

{"total": 1,
"list": [{"createdIndex": 117,
"key": "/apisix/services/1",
"value": {"enable_websocket": true,
"name": "service-test",
"update_time": 1684288908,
"create_time": 1684287870,
"id": "1",
"desc": "hello world",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1980": 1
},
"type": "roundrobin",
"scheme": "http"
},
"plugins": {"limit-count": {"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"key": "remote_addr",
"rejected_code": 503,
"time_window": 60,
"key_type": "var",
"allow_degradation": false
}
},
"hosts": ["foo.com"
]
},
"modifiedIndex": 118
}
]
}

Create Service

Create a service with an ID generated.

Request Body schema: application/json

desc	string <= 256 characters
name	string [ 1 .. 100 ] characters
	string or integer
plugins	object
	object or object
labels	object Key-value pairs to specify attributes.
enable_websocket	boolean
script	string [ 10 .. 102400 ] characters
	string or integer
hosts	Array of strings non-empty unique

Responses

Request samples

Payload

Content type

application/json

{"plugins": { },
"upstream": {"type": "roundrobin",
"nodes": {"127.0.0.1:1980": 1
}
},
"name": "service-test",
"desc": "hello world",
"enable_websocket": true,
"hosts": ["foo.com"
]
}

Response samples

201

Content type

application/json

{"value": {"enable_websocket": true,
"name": "service-test",
"update_time": 1684491069,
"create_time": 1684491069,
"plugins": { },
"id": "00000000000000000218",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1980": 1
},
"type": "roundrobin",
"scheme": "http"
},
"desc": "hello world",
"hosts": ["foo.com"
]
},
"key": "/apisix/services/00000000000000000218"
}

Get Service by ID

Get a service by ID.

path Parameters

id

required

string

The target service id

Responses

Response samples

200

Content type

application/json

{"createdIndex": 117,
"key": "/apisix/services/1",
"value": {"enable_websocket": true,
"name": "service-test",
"update_time": 1684490934,
"create_time": 1684287870,
"plugins": {"limit-count": {"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"allow_degradation": false,
"rejected_code": 503,
"time_window": 60,
"key_type": "var",
"key": "remote_addr"
}
},
"desc": "hello world",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1980": 1
},
"type": "roundrobin",
"scheme": "http"
},
"id": "1",
"hosts": ["foo.com"
]
},
"modifiedIndex": 216
}

Create Service by ID

Create a service with a custom ID.

path Parameters

id

required

string

Specifies the ID of the service resource

Request Body schema: application/json

desc	string <= 256 characters
name	string [ 1 .. 100 ] characters
	string or integer
plugins	object
	object or object
labels	object Key-value pairs to specify attributes.
enable_websocket	boolean
script	string [ 10 .. 102400 ] characters
	string or integer
hosts	Array of strings non-empty unique

Responses

Request samples

Payload

Content type

application/json

{"plugins": {"limit-count": {"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr"
}
},
"upstream": {"type": "roundrobin",
"nodes": {"127.0.0.1:1980": 1
}
},
"name": "service-test",
"desc": "hello world",
"enable_websocket": true,
"hosts": ["foo.com"
]
}

Response samples

201

Content type

application/json

{"value": {"desc": "hello world",
"name": "service-test",
"update_time": 1684491005,
"create_time": 1684287870,
"plugins": {"limit-count": {"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"key": "remote_addr",
"rejected_code": 503,
"time_window": 60,
"key_type": "var",
"allow_degradation": false
}
},
"id": "1",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1980": 1
},
"type": "roundrobin",
"scheme": "http"
},
"enable_websocket": true,
"hosts": ["foo.com"
]
},
"key": "/apisix/services/1"
}

Update Service

Update a service.

path Parameters

id

required

string

The target service id

Request Body schema: application/json

desc	string <= 256 characters
name	string [ 1 .. 100 ] characters
	string or integer
plugins	object
	object or object
labels	object Key-value pairs to specify attributes.
enable_websocket	boolean
script	string [ 10 .. 102400 ] characters
	string or integer
hosts	Array of strings non-empty unique

Responses

Request samples

Payload

Content type

application/json

{"upstream": {"nodes": {"127.0.0.1:1981": 1
}
}
}

Response samples

200

Content type

application/json

Example

Update Upstream Node To The Service

{"value": {"upstream": {"scheme": "http",
"nodes": {"127.0.0.1:1981": 1,
"127.0.0.1:1980": 1
},
"type": "roundrobin",
"hash_on": "vars",
"pass_host": "pass"
},
"create_time": 1684142130,
"enable_websocket": true,
"id": "1",
"update_time": 1684142459,
"hosts": ["foo.com"
],
"name": "service-test",
"plugins": { },
"desc": "hello world"
},
"key": "/apisix/services/1"
}

Delete Service by ID

Delete a service by ID.

path Parameters

id

required

string

The service id

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"deleted": "1",
"key": "/apisix/services/1"
}

Consumer

A consumer represents a user, application, or host that sends requests to the API gateway and consumes backend services.

See Consumers for more information.

Create Consumer

Create a consumer with a custom ID.

Request Body schema: application/json

plugins	object
username required	string [ 1 .. 100 ] characters ^[a-zA-Z0-9_]+$
labels	object Key-value pairs to specify attributes.
desc	string <= 256 characters
	string or integer

Responses

Request samples

Payload

Content type

application/json

{"username": "jack",
"plugins": {"limit-count": {"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr"
}
}
}

Response samples

201

Content type

application/json

{"key": "/apisix/consumers/jack",
"value": {"plugins": {"limit-count": {"time_window": 60,
"rejected_code": 503,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"show_limit_quota_header": true,
"allow_degradation": false,
"policy": "local"
}
},
"username": "jack",
"create_time": 1683164776,
"update_time": 1684289832
}
}

Get All Consumers

Get all configured consumers.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"plugins": {"limit-count": {"rejected_code": 503,
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local"
}
},
"username": "jack",
"create_time": 1683164776,
"update_time": 1684289832
},
"key": "/apisix/consumers/jack",
"modifiedIndex": 119,
"createdIndex": 17
}
],
"total": 1
}

Get Consumer by ID

Get a consumer by ID.

path Parameters

username

required

string

Specified consumer username.

Responses

Response samples

200

Content type

application/json

{"value": {"plugins": {"limit-count": {"rejected_code": 503,
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local"
}
},
"username": "jack",
"create_time": 1683164776,
"update_time": 1684289832
},
"key": "/apisix/consumers/jack",
"modifiedIndex": 119,
"createdIndex": 17
}

Delete Consumer by ID

Delete a consumer by ID.

path Parameters

username

required

string

Specified consumer username.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/consumers/jack",
"deleted": "1"
}

Consumer Group

A consumer group is a group of consumers sharing the same plugin configurations.

See Consumer Groups for more information.

Get All Consumer Group

Get all configured consumer groups.

Responses

Response samples

200

Content type

application/json

{"list": [{"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"
}
},
"desc": "desc",
"id": "company_a",
"create_time": 1684377809,
"update_time": 1684378459
},
"key": "/apisix/consumer_groups/company_a",
"modifiedIndex": 144,
"createdIndex": 143
}
],
"total": 1
}

Create Consumer Group by ID

Create a consumer group with a custom ID.

path Parameters

id

required

string

Specified consumer groups ID.

Request Body schema: application/json

plugins required	object
desc	string <= 256 characters
labels	object Key-value pairs to specify attributes.
required	string or integer

Responses

Request samples

Payload

Content type

application/json

{"desc": "desc",
"plugins": {"limit-count": {"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr",
"group": "consumer_group_name"
}
}
}

Response samples

201

Content type

application/json

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

Get Consumer Group by ID

Get a consumer group by ID.

path Parameters

id

required

string

Specified consumer groups ID.

Responses

Response samples

200

Content type

application/json

{"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"
}
},
"desc": "desc",
"id": "company_a",
"create_time": 1684377809,
"update_time": 1684378459
},
"key": "/apisix/consumer_groups/company_a",
"modifiedIndex": 144,
"createdIndex": 143
}

Update Consumer Group

Update a consumer group.

path Parameters

id

required

string

Specified consumer group ID.

Request Body schema: application/json

plugins required	object
desc	string <= 256 characters
labels	object Key-value pairs to specify attributes.
required	string or integer

Responses

Request samples

Payload

Content type

application/json

{"plugins": {"prometheus": { }
}
}

Response samples

200

Content type

application/json

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

Delete Consumer Group by ID

Delete a consumer group by ID.

path Parameters

id

required

string

Specified consumer group ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/consumer_groups/company_a",
"deleted": "1"
}

Credentials

A credential is an entity used to store authentication configurations associated with consumers.

See Credentials for more information.

Get All Credentials of a Consumer

Get all configured credentials of a consumer.

path Parameters

consumer

required

string

Example: john

Specified consumer username.

Responses

Response samples

200

Content type

application/json

{"total": 1,
"list": [{"total": 2,
"list": [{"key": "/apisix/consumers/john/credentials/cred-john-basic-auth",
"value": {"update_time": 1725991703,
"id": "cred-john-basic-auth",
"plugins": {"basic-auth": {"password": "john-pass",
"username": "john-key"
}
},
"create_time": 1725991529
},
"createdIndex": 42,
"modifiedIndex": 44
},
{"key": "/apisix/consumers/john/credentials/cred-john-key-auth",
"value": {"update_time": 1725991703,
"id": "cred-john-key-auth",
"plugins": {"key-auth": {"key": "john-key"
}
},
"create_time": 1725991703
},
"createdIndex": 43,
"modifiedIndex": 43
}
]
}
]
}

Get Credential by ID

Get credential of a consumer by ID.

path Parameters

consumer required	string Example: john Specified consumer username.
id required	string Example: john-key-auth-cred Specified credential ID.

Responses

Response samples

200

Content type

application/json

{"total": 1,
"list": [{"key": "/apisix/consumers/john/credentials/cred-john-basic-auth",
"value": {"update_time": 1725991529,
"id": "cred-john-basic-auth",
"plugins": {"basic-auth": {"password": "john-pass",
"username": "john-key"
}
},
"create_time": 1725991529
},
"createdIndex": 42,
"modifiedIndex": 42
}
]
}

Create Credential by ID

Create a credential by ID.

path Parameters

consumer required	string Example: john Specified consumer username.
id required	string Example: john-key-auth-cred Specified credential ID.

Request Body schema: application/json

plugins	object `basic-auth`, `key-auth`, `hmac-auth` or `jwt-auth` configurations.
label	object Key-value pairs of custom labels. When the `custom_id` label is set and if a request is authenticated, the value will be forwarded to the upstream service in the `X-Custom-ID` header.
name	string [ 1 .. 100 ] characters
desc	string <= 256 characters Description for the credential.

Responses

Request samples

Payload

Content type

application/json

{"plugins": {"key-auth": {"key": "john-key"
}
}
}

Response samples

201

Content type

application/json

{"key": "/apisix/consumers/john/credentials/cred-john-key-auth",
"value": {"create_time": 1725991703,
"id": "cred-john-key-auth",
"plugins": {"key-auth": {"key": "john-key"
}
},
"update_time": 1725991703
}
}

Delete Credential by ID

Delete a credential by ID.

path Parameters

consumer required	string Example: john Specified consumer username.
id required	string Example: john-key-auth-cred Specified credential ID.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/consumers/john/credentials/cred-john-key-auth",
"deleted": "1"
}

Plugin

Plugins extend base functionalities of APISIX to meet user-specific requirements.

See Plugins for more information.

Get All Plugin Names

Get all configured plugin names.

query Parameters

subsystem

string

Default: "http"

Enum: "http" "stream"

Example: subsystem=stream

Get HTTP or Stream plugin names.

Responses

Response samples

200

Content type

application/json

["real-ip",
"ai",
"client-control",
"proxy-control",
"request-id",
"zipkin",
"ext-plugin-pre-req",
"fault-injection",
"mocking",
"serverless-pre-function",
"cors",
"ip-restriction",
"ua-restriction",
"referer-restriction",
"csrf",
"uri-blocker",
"request-validation",
"openid-connect",
"cas-auth",
"authz-casbin",
"authz-casdoor",
"wolf-rbac",
"ldap-auth",
"hmac-auth",
"basic-auth",
"jwt-auth",
"key-auth",
"consumer-restriction",
"forward-auth",
"opa",
"authz-keycloak",
"body-transformer",
"proxy-mirror",
"proxy-cache",
"proxy-rewrite",
"workflow",
"api-breaker",
"limit-conn",
"limit-count",
"limit-req",
"gzip",
"server-info",
"traffic-split",
"redirect",
"response-rewrite",
"degraphql",
"kafka-proxy",
"grpc-transcode",
"grpc-web",
"public-api",
"prometheus",
"datadog",
"elasticsearch-logger",
"echo",
"loggly",
"http-logger",
"splunk-hec-logging",
"skywalking-logger",
"google-cloud-logging",
"sls-logger",
"tcp-logger",
"kafka-logger",
"rocketmq-logger",
"syslog",
"udp-logger",
"file-logger",
"clickhouse-logger",
"tencent-cloud-cls",
"inspect",
"example-plugin",
"aws-lambda",
"azure-functions",
"openwhisk",
"openfunction",
"serverless-post-function",
"ext-plugin-post-req",
"ext-plugin-post-resp"
]

Get Plugin Attributes by Name

Get attributes of a plugin by plugin name.

path Parameters

plugin_name

required

string

The specified plugin name

query Parameters

subsystem

string

Default: "http"

Enum: "http" "stream"

Example: subsystem=stream

Get attributes of the specified plugin name in HTTP or Stream subsystem.

Responses

Response samples

200

Content type

application/json

{"type": "object",
"then": {"properties": {"redis_port": {"type": "integer",
"default": 6379,
"minimum": 1
},
"redis_password": {"type": "string",
"minLength": 0
},
"redis_database": {"type": "integer",
"default": 0,
"minimum": 0
},
"redis_timeout": {"type": "integer",
"default": 1000,
"minimum": 1
},
"redis_host": {"type": "string",
"minLength": 2
}
},
"required": ["redis_host"
]
},
"required": ["count",
"time_window"
],
"if": {"properties": {"policy": {"enum": ["redis"
]
}
}
},
"else": {"if": {"properties": {"policy": {"enum": ["redis-cluster"
]
}
}
},
"then": {"properties": {"redis_cluster_ssl_verify": {"type": "boolean",
"default": false
},
"redis_password": {"type": "string",
"minLength": 0
},
"redis_timeout": {"type": "integer",
"default": 1000,
"minimum": 1
},
"redis_cluster_nodes": {"type": "array",
"minItems": 2,
"items": {"type": "string",
"minLength": 2,
"maxLength": 100
}
},
"redis_cluster_name": {"type": "string"
},
"redis_cluster_ssl": {"type": "boolean",
"default": false
}
},
"required": ["redis_cluster_nodes",
"redis_cluster_name"
]
}
},
"$comment": "this is a mark for our injected plugin schema",
"properties": {"_meta": {"type": "object",
"properties": {"filter": {"type": "array",
"description": "filter determines whether the plugin needs to be executed at runtime"
},
"error_response": {"oneOf": [{"type": "string"
},
{"type": "object"
}
]
},
"priority": {"type": "integer",
"description": "priority of plugins by customized order"
},
"disable": {"type": "boolean"
}
}
},
"key_type": {"type": "string",
"enum": ["var",
"var_combination",
"constant"
],
"default": "var"
},
"count": {"type": "integer",
"exclusiveMinimum": 0
},
"group": {"type": "string"
},
"rejected_code": {"type": "integer",
"default": 503,
"maximum": 599,
"minimum": 200
},
"key": {"type": "string",
"default": "remote_addr"
},
"show_limit_quota_header": {"type": "boolean",
"default": true
},
"allow_degradation": {"type": "boolean",
"default": false
},
"time_window": {"type": "integer",
"exclusiveMinimum": 0
},
"rejected_msg": {"type": "string",
"minLength": 1
},
"policy": {"type": "string",
"enum": ["local",
"redis",
"redis-cluster"
],
"default": "local"
}
}
}

Get All Plugin Attributes

Get all configured plugin attributes. This API is being deprecated soon.

query Parameters

all required	string Example: all=true Get all plugin attributes.
subsystem	string Default: "http" Enum: "http" "stream" Example: subsystem=stream Get HTTP or Stream plugin attributes.

Responses

Response samples

200

Content type

application/json

{"limit-conn": {"priority": 1003,
"version": 0.1,
"schema": {"type": "object",
"$comment": "this is a mark for our injected plugin schema",
"required": ["conn",
"burst",
"default_conn_delay",
"key"
],
"properties": {"only_use_default_delay": {"type": "boolean",
"default": false
},
"conn": {"type": "integer",
"exclusiveMinimum": 0
},
"burst": {"type": "integer",
"minimum": 0
},
"key_type": {"type": "string",
"enum": ["var",
"var_combination"
],
"default": "var"
},
"_meta": {"type": "object",
"properties": {"filter": {"type": "array",
"description": "filter determines whether the plugin needs to be executed at runtime"
},
"error_response": {"oneOf": [{"type": "string"
},
{"type": "object"
}
]
},
"priority": {"type": "integer",
"description": "priority of plugins by customized order"
},
"disable": {"type": "boolean"
}
}
},
"key": {"type": "string"
},
"default_conn_delay": {"type": "number",
"exclusiveMinimum": 0
}
}
}
},
"syslog": {"schema": {"type": "object",
"$comment": "this is a mark for our injected plugin schema",
"required": ["host",
"port"
],
"properties": {"_meta": {"type": "object",
"properties": {"filter": {"type": "array",
"description": "filter determines whether the plugin needs to be executed at runtime"
},
"error_response": {"oneOf": [{"type": "string"
},
{"type": "object"
}
]
},
"priority": {"type": "integer",
"description": "priority of plugins by customized order"
},
"disable": {"type": "boolean"
}
}
},
"host": {"type": "string"
},
"max_retry_count": {"type": "integer",
"default": 0,
"minimum": 0
},
"drop_limit": {"type": "integer",
"default": 1048576
},
"flush_limit": {"type": "integer",
"default": 4096,
"minimum": 1
},
"pool_size": {"type": "integer",
"default": 5,
"minimum": 5
},
"sock_type": {"type": "string",
"default": "tcp",
"enum": ["tcp",
"udp"
]
},
"buffer_duration": {"type": "integer",
"default": 60,
"minimum": 1
},
"retry_delay": {"type": "integer",
"default": 1,
"minimum": 0
},
"tls": {"type": "boolean",
"default": false
},
"name": {"type": "string",
"default": "stream sys logger"
},
"log_format": {"type": "object"
},
"batch_max_size": {"type": "integer",
"default": 1000,
"minimum": 1
},
"timeout": {"type": "integer",
"default": 3000,
"minimum": 1
},
"inactive_timeout": {"type": "integer",
"default": 5,
"minimum": 1
},
"port": {"type": "integer"
}
}
},
"priority": 401,
"version": 0.1,
"metadata_schema": {"type": "object",
"properties": {"log_format": {"type": "object",
"default": {"@timestamp": "$time_iso8601",
"host": "$host",
"client_ip": "$remote_addr"
}
}
}
}
},
"ip-restriction": {"priority": 3000,
"version": 0.1,
"schema": {"type": "object",
"oneOf": [{"required": ["whitelist"
]
},
{"required": ["blacklist"
]
}
],
"$comment": "this is a mark for our injected plugin schema",
"properties": {"message": {"type": "string",
"minLength": 1,
"maxLength": 1024,
"default": "Your IP address is not allowed"
},
"_meta": {"type": "object",
"properties": {"filter": {"type": "array",
"description": "filter determines whether the plugin needs to be executed at runtime"
},
"error_response": {"oneOf": [{"type": "string"
},
{"type": "object"
}
]
},
"priority": {"type": "integer",
"description": "priority of plugins by customized order"
},
"disable": {"type": "boolean"
}
}
},
"blacklist": {"type": "array",
"minItems": 1,
"items": {"anyOf": [{"type": "string",
"format": "ipv4",
"title": "IPv4"
},
{"type": "string",
"pattern": "^([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])/([12]?[0-9]|3[0-2])$",
"title": "IPv4/CIDR"
},
{"type": "string",
"format": "ipv6",
"title": "IPv6"
},
{"type": "string",
"pattern": "^([a-fA-F0-9]{0,4}:){1,8}(:[a-fA-F0-9]{0,4}){0,8}([a-fA-F0-9]{0,4})?/[0-9]{1,3}$",
"title": "IPv6/CIDR"
}
]
}
},
"whitelist": {"type": "array",
"minItems": 1,
"items": {"anyOf": [{"type": "string",
"format": "ipv4",
"title": "IPv4"
},
{"type": "string",
"pattern": "^([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])/([12]?[0-9]|3[0-2])$",
"title": "IPv4/CIDR"
},
{"type": "string",
"format": "ipv6",
"title": "IPv6"
},
{"type": "string",
"pattern": "^([a-fA-F0-9]{0,4}:){1,8}(:[a-fA-F0-9]{0,4}){0,8}([a-fA-F0-9]{0,4})?/[0-9]{1,3}$",
"title": "IPv6/CIDR"
}
]
}
}
}
}
},
"mqtt-proxy": {"priority": 1000,
"version": 0.1,
"schema": {"type": "object",
"$comment": "this is a mark for our injected plugin schema",
"required": ["protocol_name",
"protocol_level"
],
"properties": {"_meta": {"type": "object",
"properties": {"filter": {"type": "array",
"description": "filter determines whether the plugin needs to be executed at runtime"
},
"error_response": {"oneOf": [{"type": "string"
},
{"type": "object"
}
]
},
"priority": {"type": "integer",
"description": "priority of plugins by customized order"
},
"disable": {"type": "boolean"
}
}
},
"protocol_name": {"type": "string"
},
"protocol_level": {"type": "integer"
}
}
}
}
}

Reload All Plugins

Hot reload all plugins for changes to the plugin source files to take effect.

Responses

Response samples

200

Content type

application/json

"done"

Plugin Config

Plugin config is used to configure plugin configurations that can be shared among other objects, such as routes.

See Plugin Configs for more information.

Get All Plugin Configs

Get all configured plugin configs.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"plugins": {"limit-count": {"rejected_code": 503,
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local"
}
},
"desc": "desc",
"id": "1",
"create_time": 1684380007,
"update_time": 1684380034
},
"key": "/apisix/plugin_configs/1",
"modifiedIndex": 151,
"createdIndex": 150
}
],
"total": 1
}

Create Plugin Config by ID

Create a plugin config with a custom ID.

path Parameters

id

required

integer

Example: 1

Specified plugin config ID.

Request Body schema: application/json

plugins required	object
desc	string <= 256 characters
labels	object Key-value pairs to specify attributes.
required	string or integer

Responses

Request samples

Payload

Content type

application/json

{"desc": "desc",
"plugins": {"limit-count": {"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr"
}
}
}

Response samples

201

Content type

application/json

{"key": "/apisix/plugin_configs/1",
"value": {"plugins": {"limit-count": {"time_window": 60,
"rejected_code": 503,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"show_limit_quota_header": true,
"allow_degradation": false,
"policy": "local"
}
},
"desc": "desc",
"id": "1",
"create_time": 1684380007,
"update_time": 1684380034
}
}

Get Plugin Config by ID

Get a plugin config by ID.

path Parameters

id

required

string

Specified plugin config ID.

Responses

Response samples

200

Content type

application/json

{"value": {"plugins": {"limit-count": {"rejected_code": 503,
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local"
}
},
"desc": "desc",
"id": "1",
"create_time": 1684380007,
"update_time": 1684380034
},
"key": "/apisix/plugin_configs/1",
"modifiedIndex": 151,
"createdIndex": 150
}

Update Plugin Config

Update a plugin config.

path Parameters

id

required

string

Specified plugin config ID.

Request Body schema: application/json

plugins required	object
desc	string <= 256 characters
labels	object Key-value pairs to specify attributes.
required	string or integer

Responses

Request samples

Payload

Content type

application/json

{"plugins": {"prometheus": { }
}
}

Response samples

200

Content type

application/json

{"key": "/apisix/plugin_configs/1",
"value": {"plugins": {"limit-count": {"rejected_code": 503,
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local"
},
"prometheus": {"prefer_name": false
}
},
"desc": "desc",
"id": "1",
"create_time": 1684380007,
"update_time": 1684380472
}
}

Delete Plugin Config by ID

Delete a plugin config by ID.

path Parameters

id

required

string

Specified plugin config ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/plugin_configs/1",
"deleted": "1"
}

Plugin Metadata

Plugin metadata is used to configure the common metadata field(s) of all plugin instances sharing the same plugin name.

See Plugin Metadata for more information.

Get All Plugin Metadata

Get all plugin metadata.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"log_format": {"host": "$host",
"@timestamp": "$time_iso8601",
"client_ip": "$remote_addr"
}
},
"key": "/apisix/plugin_metadata/syslog",
"modifiedIndex": 283,
"createdIndex": 283
}
],
"total": 1
}

Create Plugin Metadata by Name

Create a plugin metadata by plugin name.

path Parameters

plugin_name

required

string

The specified plugin name

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"log_format": {"host": "$host",
"@timestamp": "$time_iso8601",
"client_ip": "$remote_addr"
}
}

Response samples

201

Content type

application/json

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

Get Plugin Metadata by Name

Get plugin metadata by plugin name.

path Parameters

plugin_name

required

string

The specified plugin name

Responses

Response samples

200

Content type

application/json

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

Delete Plugin Metadata by Name

Delete a plugin metadata by plugin name.

path Parameters

plugin_name

required

string

The specified plugin name

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/plugin_metadata/syslog",
"deleted": "1"
}

Global Rule

A plugin global rule is used to create plugins that are triggered on every incoming request and executed before other plugins locally bound to objects, such as routes, services, consumers, consumer groups, or plugin configs.

See Global Rules for more information.

Get All Global Rules

Get all configured plugin global rules.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"plugins": {"limit-count": {"rejected_code": 503,
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local"
}
},
"update_time": 1684375502,
"create_time": 1684375502,
"id": "1"
},
"key": "/apisix/global_rules/1",
"modifiedIndex": 137,
"createdIndex": 137
}
],
"total": 1
}

Create Global Rule by ID

Create a plugin global rule with a custom ID.

path Parameters

id

required

string

Specified global rule ID.

Request Body schema: application/json

required	string or integer
plugins required	object

Responses

Request samples

Payload

Content type

application/json

{"plugins": {"limit-count": {"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr"
}
}
}

Response samples

201

Content type

application/json

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

Get Global Rule by ID

Get a global rule by ID.

path Parameters

id

required

string

Specified global rule ID.

Responses

Response samples

200

Content type

application/json

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

Update Global Rule

Update a plugin global rule.

path Parameters

id

required

string

Specified global rule ID.

Request Body schema: application/json

	string or integer
plugins required	object

Responses

Request samples

Payload

Content type

application/json

{"plugins": {"limit-count": {"count": 3
}
}
}

Response samples

200

Content type

application/json

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

Delete Global Rule by ID

Delete a plugin global rule by ID.

path Parameters

id

required

string

Specified global rule ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/global_rules/1",
"deleted": "1"
}

Stream Route

A stream route defines a path to one or more upstream services when APISIX functions as a stream proxy that operates on the transport layer for TCP and UDP connections.

See Stream Routes for more information.

Get All Stream Routes

Get all configured stream routes.

Responses

Response samples

200

Content type

application/json

{"total": 1,
"list": [{"createdIndex": 173,
"key": "/apisix/stream_routes/1",
"value": {"id": "1",
"create_time": 1684392990,
"server_addr": "127.0.0.1",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1995": 1
},
"type": "roundrobin",
"scheme": "http"
},
"update_time": 1684392990,
"server_port": 2000
},
"modifiedIndex": 173
}
]
}

Create Stream Route

Create a stream route with an ID generated.

Request Body schema: application/json

desc	string <= 256 characters
	string or integer
	string or integer
sni	string
	string or integer
	IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) client IP
	object
	IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) server IP
	object or object
plugins	object
server_port	integer server port

Responses

Request samples

Payload

Content type

application/json

{"server_addr": "127.0.0.1",
"server_port": 2000,
"upstream": {"nodes": {"127.0.0.1:1995": 1
},
"type": "roundrobin"
}
}

Response samples

201

Content type

application/json

{"value": {"id": "00000000000000000176",
"create_time": 1684393167,
"server_addr": "127.0.0.1",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1995": 1
},
"type": "roundrobin",
"scheme": "http"
},
"update_time": 1684393167,
"server_port": 2000
},
"key": "/apisix/stream_routes/00000000000000000176"
}

Get Stream Route by ID

Get stream route by ID.

path Parameters

id

required

string

Specified stream route ID.

Responses

Response samples

200

Content type

application/json

{"id": "1",
"create_time": 1684392990,
"server_addr": "127.0.0.1",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1995": 1
},
"type": "roundrobin",
"scheme": "http"
},
"update_time": 1684392990,
"server_port": 2000
}

Create Stream Route by ID

Create a stream route with a specified ID.

path Parameters

id

required

string

Specified stream route ID.

Request Body schema: application/json

	string or integer
desc	string <= 256 characters
	string or integer
	string or integer
sni	string
	IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) client IP
	object
	IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) server IP
	object or object
plugins	object
server_port	integer server port

Responses

Request samples

Payload

Content type

application/json

{"server_addr": "127.0.0.1",
"server_port": 2000,
"upstream": {"nodes": {"127.0.0.1:1995": 1
},
"type": "roundrobin"
}
}

Response samples

201

Content type

application/json

{"value": {"id": "00000000000000000176",
"create_time": 1684393167,
"server_addr": "127.0.0.1",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1995": 1
},
"type": "roundrobin",
"scheme": "http"
},
"update_time": 1684393167,
"server_port": 2000
},
"key": "/apisix/stream_routes/00000000000000000176"
}

Delete Stream Route by ID

Delete a stream route by ID.

path Parameters

id

required

string

The stream route id

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"deleted": "1",
"key": "/apisix/stream_routes/1"
}

SSL

An SSL certificate in Admin API is required to configure TLS or mTLS with client applications and configure mTLS with upstream services.

See SSL for more information.

Get All SSL

Get all configured SSL.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"type": "server",
"key": "<content of server.key>",
"snis": ["test.com"
],
"id": "1",
"create_time": 1684373523,
"status": 1,
"cert": "<content of server.crt>",
"update_time": 1684373523
},
"key": "/apisix/ssls/1",
"modifiedIndex": 133,
"createdIndex": 133
}
],
"total": 1
}

Create SSL

Create an SSL with an ID generated.

Request Body schema: application/json

One of

labels	object Key-value pairs to specify attributes.
status	integer Default: 1 Enum: 1 0 SSL status. `1`: enable. `0`: disable.
keys	Array of strings[ items [ 128 .. 65536 ] characters ]
key required	string [ 128 .. 65536 ] characters
sni required	string
	string or integer
	object
certs	Array of strings[ items [ 128 .. 65536 ] characters ]
type	string Default: "server" Enum: "server" "client" APISIX acts as an SSL server or client.
cert required	string [ 128 .. 65536 ] characters
snis	Array of strings non-empty

Responses

Request samples

Payload

Content type

application/json

{"type": "server",
"sni": "test.com",
"cert": "<content of server.crt>",
"key": "<content of server.key>"
}

Response samples

201

Content type

application/json

{"key": "/apisix/ssls/00000000000000000134",
"value": {"type": "server",
"cert": "<content of server.crt>",
"key": "<content of server.key>",
"id": "00000000000000000134",
"create_time": 1684374944,
"status": 1,
"snis": ["test.com"
],
"update_time": 1684374944
}
}

Create an SSL by ID

Create an SSL with a custom ID.

path Parameters

id

required

string

Specified SSL ID.

Request Body schema: application/json

One of

labels	object Key-value pairs to specify attributes.
status	integer Default: 1 Enum: 1 0 SSL status. `1`: enable. `0`: disable.
keys	Array of strings[ items [ 128 .. 65536 ] characters ]
key required	string [ 128 .. 65536 ] characters
sni required	string
ssl_protocols	Array of strings Items Enum: "TLSv1.1" "TLSv1.2" "TLSv1.3"
	string or integer
	object
certs	Array of strings[ items [ 128 .. 65536 ] characters ]
type	string Default: "server" Enum: "server" "client" APISIX acts as an SSL server or client.
cert required	string [ 128 .. 65536 ] characters
snis	Array of strings non-empty

Responses

Request samples

Payload

Content type

application/json

{"type": "server",
"snis": ["test.com"
],
"cert": "<content of server.crt>",
"key": "<content of key.crt>"
}

Response samples

201

Content type

application/json

{"key": "/apisix/ssls/1",
"value": {"type": "server",
"key": "<content of server.key>",
"snis": ["test.com"
],
"id": "1",
"create_time": 1684373523,
"status": 1,
"cert": "<content of server.crt>",
"update_time": 1684373523
}
}

Get SSL by ID

Get an SSL by ID.

path Parameters

id

required

string

Specified SSL ID.

Responses

Response samples

200

Content type

application/json

{"value": {"type": "server",
"snis": ["test.com"
],
"id": "1",
"create_time": 1684373523,
"status": 1,
"cert": "<content of server.crt>",
"update_time": 1684373523
},
"key": "/apisix/ssls/1",
"modifiedIndex": 133,
"createdIndex": 133
}

Delete SSL by ID

Delete an SSL by ID.

path Parameters

id

required

string

Specified SSL ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/ssls/00000000000000000134",
"deleted": "1"
}

Secret

Secret is used to set up integration with an external secret manager, so that APISIX can establish connections and fetch secrets from the secret manager dynamically at runtime.

See Secrets for more information.

Get All Secrets

Get all configured secrets.

Responses

Response samples

200

Content type

application/json

{"total": 1,
"list": [{"createdIndex": 179,
"key": "/apisix/secrets/vault/1",
"value": {"token": "343effad",
"id": "vault/1",
"uri": "https://localhost/vault",
"prefix": "/apisix/kv",
"update_time": 1684395392,
"create_time": 1684395392
},
"modifiedIndex": 179
}
]
}

Get Secrets by ID

Get a secret by ID.

path Parameters

secretmanager required	string Enum: "vault" "aws" "gcp" Secret manager.
id required	string The specified secrets ID.

Responses

Response samples

200

Content type

application/json

{"createdIndex": 179,
"key": "/apisix/secrets/vault/1",
"value": {"token": "343effad",
"id": "vault/1",
"uri": "https://localhost/vault",
"prefix": "/apisix/kv",
"update_time": 1684395392,
"create_time": 1684395392
},
"modifiedIndex": 179
}

Create a Secret

Create a secret with a custom ID to obtain secret from secret manager.

path Parameters

secretmanager required	string Enum: "vault" "aws" "gcp" Secret manager.
id required	string The specified secrets ID.

Request Body schema: application/json

One of

uri required	string Address of the Vault server.
prefix required	string Path prefix of the secret engine that Vault should route to.
token required	string Token used for APISIX to authenticate to Vault.
namespace	string Used to set the namespace of HashiCorp Vault Enterprise and HCP Vault.

Responses

Request samples

Payload

Content type

application/json

{"uri": "https://localhost/vault",
"prefix": "/apisix/kv",
"token": "343effad",
"namespace": "apisix"
}

Response samples

201

Content type

application/json

{"value": {"prefix": "/apisix/kv",
"token": "343effad",
"uri": "https://localhost/vault",
"namespace": "apisix",
"id": "vault/1",
"update_time": 1684395392,
"create_time": 1684395392
},
"key": "/apisix/secrets/vault/1"
}

Update Secrets

Update a secret configuration.

path Parameters

secretmanager required	string Enum: "vault" "aws" "gcp" Secret manager.
id required	string The specified secrets ID.

Request Body schema: application/json

uri required	string
prefix required	string
token required	string

Responses

Request samples

Payload

Content type

application/json

{"token": "apisix"
}

Response samples

200

Content type

application/json

{"value": {"token": "apisix",
"id": "vault/1",
"uri": "https://localhost/vault",
"prefix": "/apisix/kv",
"update_time": 1684396605,
"create_time": 1684395392
},
"key": "/apisix/secrets/vault/1"
}

Delete Secret by ID

Delete a secret by ID.

path Parameters

secretmanager required	string Enum: "vault" "aws" "gcp" Secret manager.
id required	string The secrets id

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"deleted": "1",
"key": "/apisix/secrets/vault/1"
}

Proto

Proto is used to store protocol buffer (protobuf) definitions which define the service interface and message types used in communication with upstream gRPC services.

See Protos for more information.

Create Proto by ID

Create a proto with a custom ID.

path Parameters

id

required

string

Specified proto ID.

Request Body schema: application/json

content

required

string

Responses

Request samples

Payload

Content type

application/json

"{\n    \"content\": \"syntax = \\\"proto3\\\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }\"\n}"

Response samples

201

Content type

application/json

{"key": "/apisix/protos/1",
"value": {"id": "1",
"create_time": 1684752213,
"update_time": 1684752213,
"content": "syntax = \"proto3\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }"
}
}

Get Proto by ID

Get a proto configuration by ID.

path Parameters

id

required

string

Specified proto ID.

Responses

Response samples

200

Content type

application/json

{"value": {"id": "1",
"content": "syntax = \"proto3\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }",
"update_time": 1684752213,
"create_time": 1684752213
},
"key": "/apisix/protos/1",
"modifiedIndex": 292,
"createdIndex": 292
}

Delete Proto by ID

Delete a proto by ID.

path Parameters

id

required

string

Specified proto ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/protos/1",
"deleted": "1"
}

Get All Protos

Get all configured protos.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"id": "1",
"content": "syntax = \"proto3\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }",
"update_time": 1684752213,
"create_time": 1684752213
},
"key": "/apisix/protos/1",
"modifiedIndex": 292,
"createdIndex": 292
}
],
"total": 1
}

Create Proto

Create a proto with an ID generated.

Request Body schema: application/json

content

required

string

Responses

Request samples

Payload

Content type

application/json

"{\n    \"content\": \"syntax = \\\"proto3\\\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }\"\n}"

Response samples

201

Content type

application/json

{"key": "/apisix/protos/00000000000000000293",
"value": {"create_time": 1684752743,
"update_time": 1684752743,
"content": "syntax = \"proto3\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }",
"id": "00000000000000000293"
}
}

Schema Validation

Validate if the schema of a configuration is correct without sending a request to the Admin API for resource creation. This API can be used with all Admin API resources.

Validate Configuration Schema

Validate configuration schema without resource creation.

path Parameters

resource

required

string

Enum: "routes" "services" "upstreams" "consumers" "consumer_groups" "ssls" "gloabl_rules" "plugins" "plugin_metadata" "plugin_configs" "stream_routes" "secrets" "protos"

Example: routes

Type of resource.

Request Body schema: application/json

any

Responses

Request samples

Payload

Content type

application/json

{"uri": 1980,
"upstream": {"scheme": "https",
"type": "roundrobin",
"nodes": {"httpbin.org": 1
}
}
}