跳到主要内容
API docs by Redocly

Apache APISIX Admin API (3.17.0)

Download OpenAPI specification:Download

License: Apache 2.0

The Apache APISIX Admin API is a RESTful interface for managing all APISIX gateway resources — routes, upstreams, services, consumers, SSL certificates, plugins, and more.

APISIX Admin API allows you to dynamically configure the API gateway without restarts. All changes take effect immediately.

All endpoints require an API key passed via the X-API-KEY request header. The API key is configured in APISIX's config.yaml under deployment.admin.admin_key.

The default Admin API listens on http://127.0.0.1:9180. You can customize the host and port in config.yaml under deployment.admin.admin_listen.

See APISIX Documentation for more information.

Routes

A Route defines how client requests are matched and forwarded to upstream services. Routes are the most fundamental resource in APISIX — every incoming request is evaluated against configured routes.

A route must include at least a URI pattern and one of: an inline upstream, an upstream_id, a service_id, or plugins.

Key Features

  • Match by URI, host, HTTP method, headers, query parameters, and custom expressions
  • Attach plugins for authentication, rate limiting, transformation, and more
  • Support WebSocket proxying and gRPC transcoding
  • Priority-based routing when multiple routes match

See Routes documentation for more.

List All Routes

Retrieve all configured routes. Supports filtering by name, label, uri, or filter expression.

Results include full route configuration and metadata (creation/update timestamps).

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
name
string

Filter list by name (regex match).

label
string
Example: label=env

Filter list to resources with the given label key.

uri
string

Filter routes by URI (regex match against uri or any uris[]).

filter
string

Filter expression. Supports service_id and upstream_id. URL-encoded query string, e.g. service_id%3D1.

page
integer >= 1
Default: 1
Example: page=1

Page number (1-based).

page_size
integer [ 10 .. 500 ]
Example: page_size=20

Items per page (10–500). When omitted, no pagination is applied and the full list is returned.

Responses

Request samples 

curl -i http://127.0.0.1:9180/apisix/admin/routes \
  -H 'X-API-KEY: your-api-key'

Response samples

Content type
application/json
{
  • "total": 1,
  • "list": [
    ]
}

Create a Route

Create a new route with an auto-generated ID.

A route must include at least a uri and one of: upstream (inline), upstream_id, service_id, or plugins.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Route configuration body for create / replace / patch.

Any of
String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 100 ] characters

Human-readable name for the route.

desc
string <= 256 characters

Description of what this route does.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

uri
required
string [ 1 .. 4096 ] characters

URI path pattern to match. Supports exact match (/api/v1/users) and prefix match (/api/*). Mutually exclusive with uris.

uris
Array of strings non-empty unique

Multiple URI patterns. Mutually exclusive with uri.

host
string

Single hostname to match against the request's Host header. Supports wildcard prefix (*.example.com). Mutually exclusive with hosts.

hosts
Array of strings non-empty unique

Multiple hostnames to match. Mutually exclusive with host.

methods
Array of strings unique
Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE" "PURGE"

HTTP methods allowed on this route. If empty or not set, all methods are allowed.

remote_addr
string

Single client IP address or CIDR range to match. Mutually exclusive with remote_addrs.

remote_addrs
Array of strings non-empty unique

Multiple client IP addresses or CIDR ranges to match. Mutually exclusive with remote_addr.

priority
integer
Default: 0

Route priority. When multiple routes match the same request, the one with the highest priority wins.

vars
Array of any

Custom matching conditions using APISIX expressions. Each condition is an array of [variable, operator, value].

filter_func
string >= 10 characters ^function

Custom Lua function for advanced request matching. Must start with function.

required
object (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.

String ID (string) or Integer ID (integer) (ResourceId)

Reference to a Plugin Config resource. Cannot be used together with script.

Use Upstream Nodes (object) or Use Service Registry (object) (Upstream)
String ID (string) or Integer ID (integer) (ResourceId)

Reference to an existing Upstream resource.

String ID (string) or Integer ID (integer) (ResourceId)

Reference to an existing Service resource.

object (Timeout)

Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.

enable_websocket
boolean

Enable WebSocket proxying on this route.

status
integer
Default: 1
Enum: 1 0

Route status. 1 = enabled (default), 0 = disabled.

script
string [ 10 .. 102400 ] characters

Lua script for plugin orchestration. Cannot be used together with plugins or plugin_config_id.

String ID (string) or Integer ID (integer) (ResourceId)

Script ID (used internally by APISIX Dashboard).

Responses

Request samples

Content type
application/json
{
  • "name": "my-api-route",
  • "desc": "Route for user management API",
  • "uri": "/api/v1/users/*",
  • "hosts": [
    ],
  • "methods": [
    ],
  • "plugins": {
    },
  • "upstream": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/routes/00000000000000000206"
}

Create or Replace a Route

Create a new route with a specified ID, or fully replace an existing route.

Note: This is a full replacement — all fields must be provided. Use PATCH for partial updates.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Route configuration body for create / replace / patch.

Any of
String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 100 ] characters

Human-readable name for the route.

desc
string <= 256 characters

Description of what this route does.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

uri
required
string [ 1 .. 4096 ] characters

URI path pattern to match. Supports exact match (/api/v1/users) and prefix match (/api/*). Mutually exclusive with uris.

uris
Array of strings non-empty unique

Multiple URI patterns. Mutually exclusive with uri.

host
string

Single hostname to match against the request's Host header. Supports wildcard prefix (*.example.com). Mutually exclusive with hosts.

hosts
Array of strings non-empty unique

Multiple hostnames to match. Mutually exclusive with host.

methods
Array of strings unique
Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE" "PURGE"

HTTP methods allowed on this route. If empty or not set, all methods are allowed.

remote_addr
string

Single client IP address or CIDR range to match. Mutually exclusive with remote_addrs.

remote_addrs
Array of strings non-empty unique

Multiple client IP addresses or CIDR ranges to match. Mutually exclusive with remote_addr.

priority
integer
Default: 0

Route priority. When multiple routes match the same request, the one with the highest priority wins.

vars
Array of any

Custom matching conditions using APISIX expressions. Each condition is an array of [variable, operator, value].

filter_func
string >= 10 characters ^function

Custom Lua function for advanced request matching. Must start with function.

required
object (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.

String ID (string) or Integer ID (integer) (ResourceId)

Reference to a Plugin Config resource. Cannot be used together with script.

Use Upstream Nodes (object) or Use Service Registry (object) (Upstream)
String ID (string) or Integer ID (integer) (ResourceId)

Reference to an existing Upstream resource.

String ID (string) or Integer ID (integer) (ResourceId)

Reference to an existing Service resource.

object (Timeout)

Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.

enable_websocket
boolean

Enable WebSocket proxying on this route.

status
integer
Default: 1
Enum: 1 0

Route status. 1 = enabled (default), 0 = disabled.

script
string [ 10 .. 102400 ] characters

Lua script for plugin orchestration. Cannot be used together with plugins or plugin_config_id.

String ID (string) or Integer ID (integer) (ResourceId)

Script ID (used internally by APISIX Dashboard).

Responses

Request samples

Content type
application/json
{
  • "name": "payments-route",
  • "desc": "Route for payment processing API",
  • "uri": "/api/v1/payments",
  • "methods": [
    ],
  • "plugins": {
    },
  • "upstream": {
    },
  • "timeout": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/routes/1"
}

Get a Route

Retrieve a single route by its ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Responses

Request samples 

curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H 'X-API-KEY: your-api-key'

Response samples

Content type
application/json
{
  • "createdIndex": 203,
  • "key": "/apisix/routes/1",
  • "value": {
    },
  • "modifiedIndex": 203
}

Update a Route (Partial)

Partially update a route's configuration. Only the fields included in the request body are modified; all other fields remain unchanged.

Tip: Use this to update a single field (e.g., change the upstream) without resending the entire route configuration.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Route configuration body for create / replace / patch.

Any of
String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 100 ] characters

Human-readable name for the route.

desc
string <= 256 characters

Description of what this route does.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

uri
required
string [ 1 .. 4096 ] characters

URI path pattern to match. Supports exact match (/api/v1/users) and prefix match (/api/*). Mutually exclusive with uris.

uris
Array of strings non-empty unique

Multiple URI patterns. Mutually exclusive with uri.

host
string

Single hostname to match against the request's Host header. Supports wildcard prefix (*.example.com). Mutually exclusive with hosts.

hosts
Array of strings non-empty unique

Multiple hostnames to match. Mutually exclusive with host.

methods
Array of strings unique
Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE" "PURGE"

HTTP methods allowed on this route. If empty or not set, all methods are allowed.

remote_addr
string

Single client IP address or CIDR range to match. Mutually exclusive with remote_addrs.

remote_addrs
Array of strings non-empty unique

Multiple client IP addresses or CIDR ranges to match. Mutually exclusive with remote_addr.

priority
integer
Default: 0

Route priority. When multiple routes match the same request, the one with the highest priority wins.

vars
Array of any

Custom matching conditions using APISIX expressions. Each condition is an array of [variable, operator, value].

filter_func
string >= 10 characters ^function

Custom Lua function for advanced request matching. Must start with function.

required
object (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.

String ID (string) or Integer ID (integer) (ResourceId)

Reference to a Plugin Config resource. Cannot be used together with script.

Use Upstream Nodes (object) or Use Service Registry (object) (Upstream)
String ID (string) or Integer ID (integer) (ResourceId)

Reference to an existing Upstream resource.

String ID (string) or Integer ID (integer) (ResourceId)

Reference to an existing Service resource.

object (Timeout)

Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.

enable_websocket
boolean

Enable WebSocket proxying on this route.

status
integer
Default: 1
Enum: 1 0

Route status. 1 = enabled (default), 0 = disabled.

script
string [ 10 .. 102400 ] characters

Lua script for plugin orchestration. Cannot be used together with plugins or plugin_config_id.

String ID (string) or Integer ID (integer) (ResourceId)

Script ID (used internally by APISIX Dashboard).

Responses

Request samples

Content type
application/json
Example
{
  • "id": "my-route-1",
  • "name": "string",
  • "desc": "string",
  • "labels": {
    },
  • "uri": "/api/v1/users/*",
  • "uris": [
    ],
  • "host": "api.example.com",
  • "hosts": [
    ],
  • "methods": [
    ],
  • "remote_addr": "192.168.1.0/24",
  • "remote_addrs": [
    ],
  • "priority": 0,
  • "vars": [
    ],
  • "filter_func": "stringstri",
  • "plugins": {
    },
  • "plugin_config_id": "my-route-1",
  • "upstream": {
    },
  • "upstream_id": "my-route-1",
  • "service_id": "my-route-1",
  • "timeout": {
    },
  • "enable_websocket": true,
  • "status": 1,
  • "script": "stringstri",
  • "script_id": "my-route-1"
}

Response samples

Content type
application/json
Example
{
  • "value": {
    },
  • "key": "/apisix/routes/1"
}

Delete a Route

Delete a route by its ID. This action is irreversible.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
force
string
Example: force=true

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

Responses

Request samples 

curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H 'X-API-KEY: your-api-key' -X DELETE

Response samples

Content type
application/json
{
  • "deleted": "1",
  • "key": "/apisix/routes/1"
}

Replace a single nested field of a route

Replaces the value at sub_path (slash-separated nested key path within the route document, e.g. upstream/nodes) with the request body. The body is any valid JSON value, not necessarily an object.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
required
String ID (string) or Integer ID (integer) (ResourceId)
Example: r1

Resource identifier.

sub_path
required
string
Example: upstream/nodes

Slash-separated nested key path within the resource document.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
Example
{
  • "error_msg": "invalid configuration: property \"uri\" is required"
}

Upstreams

An Upstream is a virtual host abstraction over a pool of backend service nodes. It defines how APISIX distributes traffic to your backend servers.

Load Balancing Algorithms

  • roundrobin — Weighted round-robin (default)
  • chash — Consistent hashing for session affinity
  • ewma — Latency-based selection (exponentially weighted moving average)
  • least_conn — Fewest active connections

Health Checks Upstreams support active and passive health checks to automatically remove unhealthy nodes from the load balancing pool.

See Upstreams documentation for more.

List All Upstreams

Retrieve all configured upstreams.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
name
string

Filter list by name (regex match).

label
string
Example: label=env

Filter list to resources with the given label key.

page
integer >= 1
Default: 1
Example: page=1

Page number (1-based).

page_size
integer [ 10 .. 500 ]
Example: page_size=20

Items per page (10–500). When omitted, no pagination is applied and the full list is returned.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 2
}

Create an Upstream

Create a new upstream with an auto-generated ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Upstream configuration body for create / replace / patch.

One of
String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 256 ] characters

Human-readable name for the upstream.

desc
string <= 256 characters

Description of the upstream.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

required
Weight Mapping (object) or Array of Node Objects (objects)

The upstream endpoints.

retries
integer >= 0

Number of retry attempts when a request to the upstream fails.

retry_timeout
number >= 0

Maximum time in seconds for retry attempts. 0 disables the retry timeout.

object (Timeout)

Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.

type
string
Default: "roundrobin"
Enum: "roundrobin" "chash" "ewma" "least_conn"

Load balancing algorithm.

  • roundrobin — Weighted round-robin distribution (default)
  • chash — Consistent hashing for session affinity
  • ewma — Latency-based (exponentially weighted moving average)
  • least_conn — Least number of active connections
hash_on
string
Default: "vars"
Enum: "vars" "header" "cookie" "consumer" "vars_combinations"

What to hash on when type is chash.

  • vars — Hash on an NGINX variable (specified by key)
  • header — Hash on a request header (specified by key)
  • cookie — Hash on a cookie value (specified by key)
  • consumer — Hash on the authenticated consumer name
  • vars_combinations — Hash on a combination of variables
key
string

The hash key used when type is chash. Required when hash_on is header, cookie, vars, or vars_combinations. Not needed when hash_on is consumer.

scheme
string
Default: "http"
Enum: "grpc" "grpcs" "http" "https" "tcp" "tls" "udp" "kafka"

Protocol for communicating with upstream nodes.

  • L7: http, https, grpc, grpcs
  • L4: tcp, tls, udp
  • Special: kafka
Active Check (object) or Passive Check (object) (HealthCheck)

Health check configuration for monitoring upstream node availability. Active checks require at least the active field.

object (UpstreamTLS)

TLS configuration for connecting to upstream nodes over HTTPS/gRPCS.

object (KeepalivePool)

Connection pool configuration for keepalive connections to upstream nodes.

pass_host
string
Default: "pass"
Enum: "pass" "node" "rewrite"

How to set the Host header when proxying to the upstream.

  • pass — Forward the client's original Host header
  • node — Use the upstream node's hostname
  • rewrite — Use the value of upstream_host
upstream_host
string

Custom Host header value. Only effective when pass_host is rewrite.

discovery_type
string

Service discovery type (e.g., dns, consul, nacos, eureka). Required when using service discovery instead of static nodes.

object

Additional arguments for service discovery.

service_name
string [ 1 .. 256 ] characters

Service name for service discovery. Required when discovery_type is set.

Responses

Request samples

Content type
application/json
{
  • "name": "upstream-for-test",
  • "desc": "desc",
  • "scheme": "http",
  • "retries": 1,
  • "type": "roundrobin",
  • "nodes": {
    },
  • "timeout": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/upstreams/00000000000000000128",
  • "value": {
    }
}

Create or Replace an Upstream

Create a new upstream with a specified ID, or fully replace an existing upstream.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Upstream configuration body for create / replace / patch.

One of
String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 256 ] characters

Human-readable name for the upstream.

desc
string <= 256 characters

Description of the upstream.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

required
Weight Mapping (object) or Array of Node Objects (objects)

The upstream endpoints.

retries
integer >= 0

Number of retry attempts when a request to the upstream fails.

retry_timeout
number >= 0

Maximum time in seconds for retry attempts. 0 disables the retry timeout.

object (Timeout)

Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.

type
string
Default: "roundrobin"
Enum: "roundrobin" "chash" "ewma" "least_conn"

Load balancing algorithm.

  • roundrobin — Weighted round-robin distribution (default)
  • chash — Consistent hashing for session affinity
  • ewma — Latency-based (exponentially weighted moving average)
  • least_conn — Least number of active connections
hash_on
string
Default: "vars"
Enum: "vars" "header" "cookie" "consumer" "vars_combinations"

What to hash on when type is chash.

  • vars — Hash on an NGINX variable (specified by key)
  • header — Hash on a request header (specified by key)
  • cookie — Hash on a cookie value (specified by key)
  • consumer — Hash on the authenticated consumer name
  • vars_combinations — Hash on a combination of variables
key
string

The hash key used when type is chash. Required when hash_on is header, cookie, vars, or vars_combinations. Not needed when hash_on is consumer.

scheme
string
Default: "http"
Enum: "grpc" "grpcs" "http" "https" "tcp" "tls" "udp" "kafka"

Protocol for communicating with upstream nodes.

  • L7: http, https, grpc, grpcs
  • L4: tcp, tls, udp
  • Special: kafka
Active Check (object) or Passive Check (object) (HealthCheck)

Health check configuration for monitoring upstream node availability. Active checks require at least the active field.

object (UpstreamTLS)

TLS configuration for connecting to upstream nodes over HTTPS/gRPCS.

object (KeepalivePool)

Connection pool configuration for keepalive connections to upstream nodes.

pass_host
string
Default: "pass"
Enum: "pass" "node" "rewrite"

How to set the Host header when proxying to the upstream.

  • pass — Forward the client's original Host header
  • node — Use the upstream node's hostname
  • rewrite — Use the value of upstream_host
upstream_host
string

Custom Host header value. Only effective when pass_host is rewrite.

discovery_type
string

Service discovery type (e.g., dns, consul, nacos, eureka). Required when using service discovery instead of static nodes.

object

Additional arguments for service discovery.

service_name
string [ 1 .. 256 ] characters

Service name for service discovery. Required when discovery_type is set.

Responses

Request samples

Content type
application/json
{
  • "name": "backend-cluster",
  • "desc": "Primary backend service cluster",
  • "type": "roundrobin",
  • "nodes": {
    },
  • "retries": 3,
  • "retry_timeout": 5,
  • "timeout": {
    },
  • "checks": {
    },
  • "scheme": "http",
  • "pass_host": "pass"
}

Response samples

Content type
application/json
Example
{
  • "key": "/apisix/upstreams/1",
  • "value": {
    }
}

Update an Upstream (Partial)

Partially update an upstream's configuration.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Upstream configuration body for create / replace / patch.

One of
String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 256 ] characters

Human-readable name for the upstream.

desc
string <= 256 characters

Description of the upstream.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

required
Weight Mapping (object) or Array of Node Objects (objects)

The upstream endpoints.

retries
integer >= 0

Number of retry attempts when a request to the upstream fails.

retry_timeout
number >= 0

Maximum time in seconds for retry attempts. 0 disables the retry timeout.

object (Timeout)

Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.

type
string
Default: "roundrobin"
Enum: "roundrobin" "chash" "ewma" "least_conn"

Load balancing algorithm.

  • roundrobin — Weighted round-robin distribution (default)
  • chash — Consistent hashing for session affinity
  • ewma — Latency-based (exponentially weighted moving average)
  • least_conn — Least number of active connections
hash_on
string
Default: "vars"
Enum: "vars" "header" "cookie" "consumer" "vars_combinations"

What to hash on when type is chash.

  • vars — Hash on an NGINX variable (specified by key)
  • header — Hash on a request header (specified by key)
  • cookie — Hash on a cookie value (specified by key)
  • consumer — Hash on the authenticated consumer name
  • vars_combinations — Hash on a combination of variables
key
string

The hash key used when type is chash. Required when hash_on is header, cookie, vars, or vars_combinations. Not needed when hash_on is consumer.

scheme
string
Default: "http"
Enum: "grpc" "grpcs" "http" "https" "tcp" "tls" "udp" "kafka"

Protocol for communicating with upstream nodes.

  • L7: http, https, grpc, grpcs
  • L4: tcp, tls, udp
  • Special: kafka
Active Check (object) or Passive Check (object) (HealthCheck)

Health check configuration for monitoring upstream node availability. Active checks require at least the active field.

object (UpstreamTLS)

TLS configuration for connecting to upstream nodes over HTTPS/gRPCS.

object (KeepalivePool)

Connection pool configuration for keepalive connections to upstream nodes.

pass_host
string
Default: "pass"
Enum: "pass" "node" "rewrite"

How to set the Host header when proxying to the upstream.

  • pass — Forward the client's original Host header
  • node — Use the upstream node's hostname
  • rewrite — Use the value of upstream_host
upstream_host
string

Custom Host header value. Only effective when pass_host is rewrite.

discovery_type
string

Service discovery type (e.g., dns, consul, nacos, eureka). Required when using service discovery instead of static nodes.

object

Additional arguments for service discovery.

service_name
string [ 1 .. 256 ] characters

Service name for service discovery. Required when discovery_type is set.

Responses

Request samples

Content type
application/json
Example
{
  • "id": "my-route-1",
  • "name": "string",
  • "desc": "string",
  • "labels": {
    },
  • "nodes": {
    },
  • "retries": 0,
  • "retry_timeout": 0,
  • "timeout": {
    },
  • "type": "roundrobin",
  • "hash_on": "vars",
  • "key": "string",
  • "scheme": "grpc",
  • "checks": {
    },
  • "tls": {
    },
  • "keepalive_pool": {
    },
  • "pass_host": "pass",
  • "upstream_host": "string",
  • "discovery_type": "string",
  • "discovery_args": {
    },
  • "service_name": "string"
}

Response samples

Content type
application/json
{
  • "key": "/apisix/upstreams/1",
  • "value": {
    }
}

Get an Upstream

Retrieve a single upstream by its ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/upstreams/1",
  • "modifiedIndex": 126,
  • "createdIndex": 121
}

Delete an Upstream

Delete an upstream by its ID. Fails if the upstream is still referenced by a route or service.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
force
string
Example: force=true

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

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/upstreams/1",
  • "deleted": "1"
}

Replace a single nested field of a upstream

Replaces the value at sub_path (slash-separated nested key path within the upstream document, e.g. upstream/nodes) with the request body. The body is any valid JSON value, not necessarily an object.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
required
String ID (string) or Integer ID (integer) (ResourceId)
Example: r1

Resource identifier.

sub_path
required
string
Example: upstream/nodes

Slash-separated nested key path within the resource document.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
Example
{
  • "error_msg": "invalid configuration: property \"uri\" is required"
}

Services

A Service is a reusable abstraction that groups an upstream and a set of plugins. Multiple routes can reference the same service, reducing configuration duplication.

When a route references a service via service_id, the service's upstream and plugins are merged with the route's own configuration. Route-level settings take precedence.

See Services documentation for more.

List All Services

Retrieve all configured services.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
name
string

Filter list by name (regex match).

label
string
Example: label=env

Filter list to resources with the given label key.

page
integer >= 1
Default: 1
Example: page=1

Page number (1-based).

page_size
integer [ 10 .. 500 ]
Example: page_size=20

Items per page (10–500). When omitted, no pagination is applied and the full list is returned.

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "list": [
    ]
}

Create a Service

Create a new service with an auto-generated ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Service configuration body for create / replace / patch.

String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 256 ] characters

Human-readable name.

desc
string <= 256 characters

Description of this service.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

object (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.

Use Upstream Nodes (object) or Use Service Registry (object) (Upstream)
String ID (string) or Integer ID (integer) (ResourceId)

Reference to an existing Upstream resource.

script
string [ 10 .. 102400 ] characters

Lua script for plugin orchestration.

enable_websocket
boolean

Enable WebSocket proxying for routes using this service.

hosts
Array of strings non-empty unique

Hostnames associated with this service.

Responses

Request samples

Content type
application/json
{
  • "plugins": { },
  • "upstream": {
    },
  • "name": "service-test",
  • "desc": "hello world",
  • "enable_websocket": true,
  • "hosts": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/services/00000000000000000218"
}

Get a Service

Retrieve a single service by its ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Responses

Response samples

Content type
application/json
{
  • "createdIndex": 117,
  • "key": "/apisix/services/1",
  • "value": {
    },
  • "modifiedIndex": 216
}

Create or Replace a Service

Create a new service with a specified ID, or fully replace an existing service.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Service configuration body for create / replace / patch.

String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 256 ] characters

Human-readable name.

desc
string <= 256 characters

Description of this service.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

object (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.

Use Upstream Nodes (object) or Use Service Registry (object) (Upstream)
String ID (string) or Integer ID (integer) (ResourceId)

Reference to an existing Upstream resource.

script
string [ 10 .. 102400 ] characters

Lua script for plugin orchestration.

enable_websocket
boolean

Enable WebSocket proxying for routes using this service.

hosts
Array of strings non-empty unique

Hostnames associated with this service.

Responses

Request samples

Content type
application/json
{
  • "name": "user-service",
  • "desc": "User management microservice",
  • "upstream": {
    },
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/services/1"
}

Update a Service (Partial)

Partially update a service's configuration.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Service configuration body for create / replace / patch.

String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 256 ] characters

Human-readable name.

desc
string <= 256 characters

Description of this service.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

object (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.

Use Upstream Nodes (object) or Use Service Registry (object) (Upstream)
String ID (string) or Integer ID (integer) (ResourceId)

Reference to an existing Upstream resource.

script
string [ 10 .. 102400 ] characters

Lua script for plugin orchestration.

enable_websocket
boolean

Enable WebSocket proxying for routes using this service.

hosts
Array of strings non-empty unique

Hostnames associated with this service.

Responses

Request samples

Content type
application/json
{
  • "id": "my-route-1",
  • "name": "string",
  • "desc": "string",
  • "labels": {
    },
  • "plugins": {
    },
  • "upstream": {
    },
  • "upstream_id": "my-route-1",
  • "script": "stringstri",
  • "enable_websocket": true,
  • "hosts": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/services/1"
}

Delete a Service

Delete a service by its ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
force
string
Example: force=true

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

Responses

Response samples

Content type
application/json
{
  • "deleted": "1",
  • "key": "/apisix/services/1"
}

Replace a single nested field of a service

Replaces the value at sub_path (slash-separated nested key path within the service document, e.g. upstream/nodes) with the request body. The body is any valid JSON value, not necessarily an object.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
required
String ID (string) or Integer ID (integer) (ResourceId)
Example: r1

Resource identifier.

sub_path
required
string
Example: upstream/nodes

Slash-separated nested key path within the resource document.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
Example
{
  • "error_msg": "invalid configuration: property \"uri\" is required"
}

Consumers

A Consumer represents an API user, application, or host that consumes your APIs. Consumers are typically used with authentication plugins (e.g., key-auth, jwt-auth) to identify callers and apply per-consumer rate limits or access controls.

Each consumer is uniquely identified by a username and can belong to a consumer group.

See Consumers documentation for more.

Create or Update a Consumer

Create a new consumer or update an existing one. The consumer is identified by username in the request body.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Consumer configuration body for create / replace / patch.

username
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9_\-]+$

Unique username for the consumer. Only alphanumeric characters, hyphens, and underscores are allowed.

desc
string <= 256 characters

Description of this consumer.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

String ID (string) or Integer ID (integer) (ResourceId)

Reference to a Consumer Group for shared plugin configurations.

object (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.

Responses

Request samples

Content type
application/json
{
  • "username": "my-app",
  • "desc": "Mobile application consumer",
  • "labels": {
    },
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/consumers/jack",
  • "value": {
    }
}

List All Consumers

Retrieve all configured consumers.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
label
string
Example: label=env

Filter list to resources with the given label key.

page
integer >= 1
Default: 1
Example: page=1

Page number (1-based).

page_size
integer [ 10 .. 500 ]
Example: page_size=20

Items per page (10–500). When omitted, no pagination is applied and the full list is returned.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a Consumer

Retrieve a single consumer by username.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
username
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9_\-]+$
Example: jack

Consumer username.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/consumers/jack",
  • "modifiedIndex": 119,
  • "createdIndex": 17
}

Delete a Consumer

Delete a consumer by username. This also deletes all associated credentials.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
username
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9_\-]+$
Example: jack

Consumer username.

query Parameters
force
string
Example: force=true

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

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/consumers/jack",
  • "deleted": "1"
}

Consumer Groups

A Consumer Group allows you to define shared plugin configurations that apply to multiple consumers. Instead of duplicating plugin settings across consumers, assign them to a group.

Consumers reference a group via the group_id field. Group-level plugins are merged with consumer-level plugins, with consumer-level taking precedence.

See Consumer Groups documentation for more.

List All Consumer Groups

Retrieve all configured consumer groups.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
name
string

Filter list by name (regex match).

label
string
Example: label=env

Filter list to resources with the given label key.

page
integer >= 1
Default: 1
Example: page=1

Page number (1-based).

page_size
integer [ 10 .. 500 ]
Example: page_size=20

Items per page (10–500). When omitted, no pagination is applied and the full list is returned.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create or Replace a Consumer Group

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

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

ConsumerGroup configuration body for create / replace / patch.

String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 256 ] characters

Human-readable name.

desc
string <= 256 characters

Description of this group.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

required
object (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.

Responses

Request samples

Content type
application/json
{
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/consumer_groups/company_a",
  • "value": {
    }
}

Get a Consumer Group

Retrieve a single consumer group by its ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/consumer_groups/company_a",
  • "modifiedIndex": 144,
  • "createdIndex": 143
}

Update a Consumer Group (Partial)

Partially update a consumer group's configuration.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

ConsumerGroup configuration body for create / replace / patch.

String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 256 ] characters

Human-readable name.

desc
string <= 256 characters

Description of this group.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

required
object (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.

Responses

Request samples

Content type
application/json
{
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/consumer_groups/company_a",
  • "value": {
    }
}

Delete a Consumer Group

Delete a consumer group by its ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
force
string
Example: force=true

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

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/consumer_groups/company_a",
  • "deleted": "1"
}

Replace a single nested field of a consumer group

Replaces the value at sub_path (slash-separated nested key path within the consumer group document, e.g. upstream/nodes) with the request body. The body is any valid JSON value, not necessarily an object.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
required
String ID (string) or Integer ID (integer) (ResourceId)
Example: r1

Resource identifier.

sub_path
required
string
Example: upstream/nodes

Slash-separated nested key path within the resource document.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
Example
{
  • "error_msg": "invalid configuration: property \"uri\" is required"
}

Credentials

A Credential stores authentication configuration associated with a consumer. Each credential holds exactly one authentication plugin (e.g., key-auth, basic-auth, jwt-auth).

Credentials are sub-resources of consumers. A consumer can have multiple credentials, each for a different authentication method.

See Credentials documentation for more.

List Consumer Credentials

Retrieve all credentials for a specific consumer.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
username
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9_\-]+$
Example: jack

Consumer username.

query Parameters
name
string

Filter list by name (regex match).

label
string
Example: label=env

Filter list to resources with the given label key.

page
integer >= 1
Default: 1
Example: page=1

Page number (1-based).

page_size
integer [ 10 .. 500 ]
Example: page_size=20

Items per page (10–500). When omitted, no pagination is applied and the full list is returned.

Responses

Response samples

Content type
application/json
{
  • "total": 2,
  • "list": [
    ]
}

Get a Credential

Retrieve a specific credential for a consumer.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
username
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9_\-]+$
Example: jack

Consumer username.

id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "list": [
    ]
}

Create or Replace a Credential

Create a new credential for a consumer with a specified ID, or replace an existing one.

Each credential holds exactly one authentication plugin.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
username
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9_\-]+$
Example: jack

Consumer username.

id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Credential configuration body for create / replace / patch.

String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 256 ] characters

Human-readable name.

desc
string <= 256 characters

Description of this credential.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

plugins
object <= 1 properties

Exactly one authentication plugin configuration (e.g., key-auth, basic-auth, jwt-auth).

Responses

Request samples

Content type
application/json
{
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/consumers/john/credentials/cred-john-key-auth",
  • "value": {
    }
}

Delete a Credential

Delete a specific credential from a consumer.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
username
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9_\-]+$
Example: jack

Consumer username.

id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
force
string
Value: "true"
Example: force=true

When true, skip dependency checks before deletion.

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/consumers/john/credentials/cred-john-key-auth",
  • "deleted": "1"
}

Plugins

Plugins extend APISIX's core functionality with middleware capabilities such as authentication, traffic control, observability, and request/response transformation.

Use these endpoints to query available plugins and their JSON schemas, or to hot-reload plugins without restarting APISIX.

Plugins are attached to routes, services, consumers, or global rules via the plugins object.

See Plugin Hub for the full list of available plugins.

List Plugin Names

Get a list of all available plugin names, optionally filtered by subsystem (http or stream).

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
subsystem
string
Default: "http"
Enum: "http" "stream"

Plugin subsystem.

Responses

Response samples

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 JSON Schema

Retrieve the JSON Schema definition for a specific plugin. This is useful for validating plugin configurations before applying them.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
plugin_name
required
string non-empty
Example: limit-count

Plugin name.

query Parameters
subsystem
string
Default: "http"
Enum: "http" "stream"

Plugin subsystem.

Responses

Response samples

Content type
application/json
{
  • "$comment": "this is a mark for our injected plugin schema.",
  • "type": "object",
  • "required": [
    ],
  • "properties": {
    },
  • "if": {
    },
  • "then": {
    },
  • "else": {
    }
}

List Plugin Attributes

Get attributes of all plugins configured on the APISIX instance.

Deprecated: This endpoint is being replaced. Use GET /plugins/list and GET /plugins/{plugin_name} instead.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
all
string
Deprecated
Value: "true"

Deprecated. When true, return the full plugin catalog.

subsystem
string
Default: "http"
Enum: "http" "stream"

Plugin subsystem.

Responses

Response samples

Content type
application/json
{
  • "limit-conn": {
    },
  • "syslog": {
    },
  • "ip-restriction": {
    },
  • "mqtt-proxy": {
    }
}

Hot-Reload Plugins

Trigger a hot reload of all plugins. This re-reads plugin configurations from etcd without restarting APISIX.

Important: Only the PUT method is accepted.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie

Responses

Request samples 

curl -i http://127.0.0.1:9180/apisix/admin/plugins/reload \
  -H 'X-API-KEY: your-api-key' -X PUT

Response samples

Content type
application/json
"done"

Plugin Configs

A Plugin Config is a reusable set of plugin configurations that can be shared across multiple routes. Instead of duplicating plugin settings in each route, create a plugin config and reference it via plugin_config_id.

Route-level plugins are merged with plugin config plugins, with route-level taking precedence.

See Plugin Configs documentation for more.

List All Plugin Configs

Retrieve all configured plugin configs.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
name
string

Filter list by name (regex match).

label
string
Example: label=env

Filter list to resources with the given label key.

page
integer >= 1
Default: 1
Example: page=1

Page number (1-based).

page_size
integer [ 10 .. 500 ]
Example: page_size=20

Items per page (10–500). When omitted, no pagination is applied and the full list is returned.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create or Replace a Plugin Config

Create a new plugin config with a specified ID, or fully replace an existing one.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
integer

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

PluginConfig configuration body for create / replace / patch.

String ID (string) or Integer ID (integer) (ResourceId)

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

name
string

Human-readable name.

desc
string <= 256 characters

Description.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

required
object (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.

Responses

Request samples

Content type
application/json
{
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/plugin_configs/1",
  • "value": {
    }
}

Get a Plugin Config

Retrieve a single plugin config by its ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/plugin_configs/1",
  • "modifiedIndex": 151,
  • "createdIndex": 150
}

Update a Plugin Config (Partial)

Partially update a plugin config's configuration.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

PluginConfig configuration body for create / replace / patch.

String ID (string) or Integer ID (integer) (ResourceId)

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

name
string

Human-readable name.

desc
string <= 256 characters

Description.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

required
object (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.

Responses

Request samples

Content type
application/json
{
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/plugin_configs/1",
  • "value": {
    }
}

Delete a Plugin Config

Delete a plugin config by its ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
force
string
Example: force=true

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

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/plugin_configs/1",
  • "deleted": "1"
}

Replace a single nested field of a plugin config

Replaces the value at sub_path (slash-separated nested key path within the plugin config document, e.g. upstream/nodes) with the request body. The body is any valid JSON value, not necessarily an object.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
required
String ID (string) or Integer ID (integer) (ResourceId)
Example: r1

Resource identifier.

sub_path
required
string
Example: upstream/nodes

Slash-separated nested key path within the resource document.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
Example
{
  • "error_msg": "invalid configuration: property \"uri\" is required"
}

Plugin Metadata

Plugin Metadata configures shared settings that apply to all instances of a specific plugin across the entire APISIX cluster. This is useful for plugins that need global configuration, such as log format templates.

For example, setting metadata for http-logger will affect every route that uses http-logger.

See Plugin Metadata documentation for more.

List All Plugin Metadata

Retrieve metadata for all plugins that have metadata configured.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number (1-based).

page_size
integer [ 10 .. 500 ]
Example: page_size=20

Items per page (10–500). When omitted, no pagination is applied and the full list is returned.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create or Replace Plugin Metadata

Set metadata for a specific plugin. This applies to all instances of the plugin across the cluster.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
plugin_name
required
string non-empty
Example: limit-count

Plugin name.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Plugin metadata. The body schema is plugin-specific (the plugin's metadata_schema). Fetch via GET /apisix/admin/schema/plugins/{plugin_name}.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "key": "/apisix/plugin_metadata/syslog",
  • "value": {
    }
}

Get Plugin Metadata

Retrieve metadata for a specific plugin by plugin name.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
plugin_name
required
string non-empty
Example: limit-count

Plugin name.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/plugin_metadata/syslog",
  • "modifiedIndex": 156,
  • "createdIndex": 156
}

Delete Plugin Metadata

Delete metadata for a specific plugin.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
plugin_name
required
string non-empty
Example: limit-count

Plugin name.

query Parameters
force
string
Example: force=true

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

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/plugin_metadata/syslog",
  • "deleted": "1"
}

Global Rules

A Global Rule defines plugins that are executed on every incoming request, before any route-specific plugins run. Use global rules for cross-cutting concerns like IP allowlists, request logging, or metrics collection.

Global rules are evaluated in order of their id. Plugin execution order within a global rule follows standard APISIX plugin priority.

See Global Rules documentation for more.

List All Global Rules

Retrieve all configured global rules.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
name
string

Filter list by name (regex match).

label
string
Example: label=env

Filter list to resources with the given label key.

page
integer >= 1
Default: 1
Example: page=1

Page number (1-based).

page_size
integer [ 10 .. 500 ]
Example: page_size=20

Items per page (10–500). When omitted, no pagination is applied and the full list is returned.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create or Replace a Global Rule

Create a new global rule with a specified ID, or fully replace an existing one.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

GlobalRule configuration body for create / replace / patch.

String ID (string) or Integer ID (integer) (ResourceId)

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

required
object (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.

Responses

Request samples

Content type
application/json
{
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/global_rules/1",
  • "value": {
    }
}

Get a Global Rule

Retrieve a single global rule by its ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/global_rules/1",
  • "modifiedIndex": 137,
  • "createdIndex": 137
}

Update a Global Rule (Partial)

Partially update a global rule's configuration.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

GlobalRule configuration body for create / replace / patch.

String ID (string) or Integer ID (integer) (ResourceId)

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

required
object (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.

Responses

Request samples

Content type
application/json
{
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/global_rules/1",
  • "value": {
    }
}

Delete a Global Rule

Delete a global rule by its ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
force
string
Example: force=true

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

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/global_rules/1",
  • "deleted": "1"
}

Replace a single nested field of a global rule

Replaces the value at sub_path (slash-separated nested key path within the global rule document, e.g. upstream/nodes) with the request body. The body is any valid JSON value, not necessarily an object.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
required
String ID (string) or Integer ID (integer) (ResourceId)
Example: r1

Resource identifier.

sub_path
required
string
Example: upstream/nodes

Slash-separated nested key path within the resource document.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
Example
{
  • "error_msg": "invalid configuration: property \"uri\" is required"
}

Stream Routes

A Stream Route defines TCP/UDP layer (L4) proxying rules. Unlike HTTP routes, stream routes operate at the transport layer and can proxy raw TCP and UDP connections.

Stream routes match traffic by remote_addr, server_addr, server_port, or sni (for TLS connections).

Note: Stream mode must be enabled in config.yaml (apisix.proxy_mode: stream or http&stream) before creating stream routes.

See Stream Routes documentation for more.

List All Stream Routes

Retrieve all configured stream (L4) routes.

Prerequisite: Stream mode must be enabled in config.yaml.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
name
string

Filter list by name (regex match).

label
string
Example: label=env

Filter list to resources with the given label key.

filter
string

Filter expression. Supports service_id and upstream_id. URL-encoded query string, e.g. service_id%3D1.

page
integer >= 1
Default: 1
Example: page=1

Page number (1-based).

page_size
integer [ 10 .. 500 ]
Example: page_size=20

Items per page (10–500). When omitted, no pagination is applied and the full list is returned.

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "list": [
    ]
}

Create a Stream Route

Create a new stream route with an auto-generated ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

StreamRoute configuration body for create / replace / patch.

String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 256 ] characters

Human-readable name.

desc
string <= 256 characters

Description.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

remote_addr
string

Client IP address or CIDR range to match.

server_addr
string

Server IP address to match.

server_port
integer [ 1 .. 65535 ]

Server port to match.

sni
string

SNI hostname to match (for TLS connections).

Use Upstream Nodes (object) or Use Service Registry (object) (Upstream)
String ID (string) or Integer ID (integer) (ResourceId)

Reference to an existing Upstream.

String ID (string) or Integer ID (integer) (ResourceId)

Reference to an existing Service.

object (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.

Responses

Request samples

Content type
application/json
{
  • "server_addr": "127.0.0.1",
  • "server_port": 2000,
  • "upstream": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/stream_routes/00000000000000000176"
}

Get Stream Route by ID

Get stream route by ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Responses

Response samples

Content type
application/json
{
  • "id": "1",
  • "create_time": 1684392990,
  • "server_addr": "127.0.0.1",
  • "upstream": {
    },
  • "update_time": 1684392990,
  • "server_port": 2000
}

Create Stream Route by ID

Create a stream route with a specified ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

StreamRoute configuration body for create / replace / patch.

String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 256 ] characters

Human-readable name.

desc
string <= 256 characters

Description.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

remote_addr
string

Client IP address or CIDR range to match.

server_addr
string

Server IP address to match.

server_port
integer [ 1 .. 65535 ]

Server port to match.

sni
string

SNI hostname to match (for TLS connections).

Use Upstream Nodes (object) or Use Service Registry (object) (Upstream)
String ID (string) or Integer ID (integer) (ResourceId)

Reference to an existing Upstream.

String ID (string) or Integer ID (integer) (ResourceId)

Reference to an existing Service.

object (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.

Responses

Request samples

Content type
application/json
{
  • "server_addr": "127.0.0.1",
  • "server_port": 2000,
  • "upstream": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/stream_routes/00000000000000000176"
}

Delete Stream Route by ID

Delete a stream route by ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
force
string
Example: force=true

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

Responses

Response samples

Content type
application/json
{
  • "deleted": "1",
  • "key": "/apisix/stream_routes/1"
}

SSL Certificates

The SSL resource manages TLS certificates for HTTPS termination and mTLS authentication.

Certificate Types

  • server — Server certificate for HTTPS termination (matched by SNI)
  • client — Client certificate for mTLS with upstream services

APISIX dynamically selects the correct certificate based on the SNI (Server Name Indication) in the TLS handshake. Certificates can be rotated without restart.

See SSL documentation for more.

List All SSL Certificates

Retrieve all configured SSL certificates. Private keys are not included in the response for security.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
label
string
Example: label=env

Filter list to resources with the given label key.

page
integer >= 1
Default: 1
Example: page=1

Page number (1-based).

page_size
integer [ 10 .. 500 ]
Example: page_size=20

Items per page (10–500). When omitted, no pagination is applied and the full list is returned.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create an SSL Certificate

Upload a new SSL certificate with an auto-generated ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

SSL configuration body for create / replace / patch.

One of
One of
String ID (string) or Integer ID (integer) (ResourceId)

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

desc
string <= 256 characters

Description.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

type
string
Default: "server"
Enum: "server" "client"

Certificate type.

  • server — For HTTPS termination (matched by SNI)
  • client — Client certificate for mTLS with upstream services
sni
required
string

Server Name Indication (SNI) to match. Supports wildcard prefix (*.example.com). Mutually exclusive with snis.

snis
Array of strings non-empty

Multiple SNI hostnames. Mutually exclusive with sni.

cert
required
string [ 128 .. 65536 ] characters

PEM-encoded server certificate. Can also be a secret reference ($secret://...).

key
required
string [ 128 .. 65536 ] characters

PEM-encoded private key. Can also be a secret reference ($secret://...). Not returned in GET responses for security.

certs
Array of strings

Additional certificates for certificate chain or alternative key types.

keys
Array of strings

Additional private keys corresponding to certs.

object

mTLS client verification settings.

status
integer
Default: 1
Enum: 1 0

SSL status. 1 = enabled, 0 = disabled.

ssl_protocols
Array of strings <= 3 items unique
Items Enum: "TLSv1.1" "TLSv1.2" "TLSv1.3"

Allowed TLS protocol versions.

Responses

Request samples

Content type
application/json
{
  • "type": "server",
  • "sni": "test.com",
  • "cert": "-----BEGIN CERTIFICATE-----\nMIIDazCCAlOgAwIBAgIUJ9hQk3kXgZeZpY/m/0V6RmH1AbcwDQYJKoZIhvcNAQEL\nBQAwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM\nGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMB4XDTI1MDEwMTAwMDAwMFoXDTM1\nMDEwMTAwMDAwMFowRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUx\nITAfBgNVBAoMGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4eXAMPLEcaPUBLIcfakeforopeNAPIspecON\nLYexampleCAcontentsoExpandedFakeKeyMaterial==\n-----END CERTIFICATE-----\n",
  • "key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDh5cAWYXAMPLEbe\nfakekeyForOpenAPISpecPlaceholderOnlyDoNotUseForRealKeysNopeNopeNo\npeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNo\npeNopeNopeNopeNopeNopeNope==\n-----END PRIVATE KEY-----\n"
}

Response samples

Content type
application/json
{
  • "key": "/apisix/ssls/00000000000000000134",
  • "value": {
    }
}

Create or Replace an SSL Certificate

Upload a new SSL certificate with a specified ID, or replace an existing one.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

SSL configuration body for create / replace / patch.

One of
One of
String ID (string) or Integer ID (integer) (ResourceId)

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

desc
string <= 256 characters

Description.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

type
string
Default: "server"
Enum: "server" "client"

Certificate type.

  • server — For HTTPS termination (matched by SNI)
  • client — Client certificate for mTLS with upstream services
sni
required
string

Server Name Indication (SNI) to match. Supports wildcard prefix (*.example.com). Mutually exclusive with snis.

snis
Array of strings non-empty

Multiple SNI hostnames. Mutually exclusive with sni.

cert
required
string [ 128 .. 65536 ] characters

PEM-encoded server certificate. Can also be a secret reference ($secret://...).

key
required
string [ 128 .. 65536 ] characters

PEM-encoded private key. Can also be a secret reference ($secret://...). Not returned in GET responses for security.

certs
Array of strings

Additional certificates for certificate chain or alternative key types.

keys
Array of strings

Additional private keys corresponding to certs.

object

mTLS client verification settings.

status
integer
Default: 1
Enum: 1 0

SSL status. 1 = enabled, 0 = disabled.

ssl_protocols
Array of strings <= 3 items unique
Items Enum: "TLSv1.1" "TLSv1.2" "TLSv1.3"

Allowed TLS protocol versions.

Responses

Request samples

Content type
application/json
{
  • "type": "server",
  • "sni": "api.example.com",
  • "cert": "-----BEGIN CERTIFICATE-----\nMIIDazCCAlOgAwIBAgIUJ9hQk3kXgZeZpY/m/0V6RmH1AbcwDQYJKoZIhvcNAQEL\nBQAwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM\nGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMB4XDTI1MDEwMTAwMDAwMFoXDTM1\nMDEwMTAwMDAwMFowRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUx\nITAfBgNVBAoMGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4eXAMPLEcaPUBLIcfakeforopeNAPIspecON\nLYexampleCAcontentsoExpandedFakeKeyMaterial==\n-----END CERTIFICATE-----\n",
  • "key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDh5cAWYXAMPLEbe\nfakekeyForOpenAPISpecPlaceholderOnlyDoNotUseForRealKeysNopeNopeNo\npeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNo\npeNopeNopeNopeNopeNopeNope==\n-----END PRIVATE KEY-----\n"
}

Response samples

Content type
application/json
{
  • "key": "/apisix/ssls/1",
  • "value": {
    }
}

Get an SSL Certificate

Retrieve a single SSL certificate by its ID. The private key is not included in the response.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/ssls/1",
  • "modifiedIndex": 133,
  • "createdIndex": 133
}

Delete an SSL Certificate

Delete an SSL certificate by its ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
force
string
Example: force=true

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

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/ssls/00000000000000000134",
  • "deleted": "1"
}

Replace a single nested field of a SSL

Replaces the value at sub_path (slash-separated nested key path within the SSL document, e.g. upstream/nodes) with the request body. The body is any valid JSON value, not necessarily an object.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
required
String ID (string) or Integer ID (integer) (ResourceId)
Example: r1

Resource identifier.

sub_path
required
string
Example: upstream/nodes

Slash-separated nested key path within the resource document.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
Example
{
  • "error_msg": "invalid configuration: property \"uri\" is required"
}

Secrets

The Secret resource integrates APISIX with external secret managers (e.g., HashiCorp Vault, AWS Secrets Manager) for dynamic secret retrieval at runtime.

Once configured, you can reference secrets in plugin configurations using the URI format: $secret://vault/my-secret/key.

See Secrets documentation for more.

List All Secrets

Retrieve all configured secret manager integrations.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number (1-based).

page_size
integer [ 10 .. 500 ]
Example: page_size=20

Items per page (10–500). When omitted, no pagination is applied and the full list is returned.

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "list": [
    ]
}

Get a Secret

Retrieve a specific secret manager configuration.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
secret_type
required
string
Enum: "vault" "aws" "gcp"
Example: vault

Type of secret manager (e.g., vault, aws).

id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Responses

Response samples

Content type
application/json
{
  • "createdIndex": 179,
  • "key": "/apisix/secrets/vault/1",
  • "value": {
    },
  • "modifiedIndex": 179
}

Create or Replace a Secret

Configure a secret manager integration with a specified ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
secret_type
required
string
Enum: "vault" "aws" "gcp"
Example: vault

Type of secret manager (e.g., vault, aws).

id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Secret manager configuration (schema depends on secret_type).

property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/secrets/vault/1"
}

Update a Secret (Partial)

Partially update a secret manager configuration.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
secret_type
required
string
Enum: "vault" "aws" "gcp"
Example: vault

Type of secret manager (e.g., vault, aws).

id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Secret manager configuration (schema depends on secret_type).

property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/secrets/vault/1"
}

Delete a Secret

Delete a secret manager configuration.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
secret_type
required
string
Enum: "vault" "aws" "gcp"
Example: vault

Type of secret manager (e.g., vault, aws).

id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
force
string
Example: force=true

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

Responses

Response samples

Content type
application/json
{
  • "deleted": "1",
  • "key": "/apisix/secrets/vault/1"
}

List secrets of a single secret-manager type

Returns secrets registered under the given manager (vault, aws, or gcp). For listing across all managers, use GET /apisix/admin/secrets.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
secret_type
required
string
Enum: "vault" "aws" "gcp"
Example: vault

Secret manager backend.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "list": [
    ]
}

Replace a single nested field of a secret

Replaces the value at sub_path within a secret object.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
secret_type
required
string
Enum: "vault" "aws" "gcp"
Example: vault

Secret manager backend.

required
String ID (string) or Integer ID (integer) (ResourceId)
Example: r1

Resource identifier.

sub_path
required
string
Example: upstream/nodes

Slash-separated nested key path within the resource document.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
Example
{
  • "error_msg": "failed to check token",
  • "description": "missing apikey"
}

Protos

The Proto resource stores Protocol Buffer (protobuf) .proto file content used by the grpc-transcode plugin to convert between HTTP/JSON and gRPC.

Upload your .proto definitions here, then reference them by ID in the grpc-transcode plugin configuration.

See gRPC Transcode plugin for more.

Create or Replace a Proto

Upload a protobuf definition with a specified ID, or replace an existing one.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Proto configuration body for create / replace / patch.

String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 256 ] characters

Human-readable name.

desc
string <= 256 characters

Description.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

content
required
string [ 1 .. 1048576 ] characters

Protobuf .proto file content as a string.

Responses

Request samples

Content type
application/json
{
  • "content": "syntax = \"proto3\";\n\npackage helloworld;\n\nservice Greeter {\n rpc SayHello (HelloRequest) returns (HelloReply) {}\n}\n\nmessage HelloRequest {\n string name = 1;\n}\n\nmessage HelloReply {\n string message = 1;\n}"
}

Response samples

Content type
application/json
{
  • "key": "/apisix/protos/1",
  • "value": {
    }
}

Get a Proto

Retrieve a single protobuf definition by its ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/protos/1",
  • "modifiedIndex": 292,
  • "createdIndex": 292
}

Delete a Proto

Delete a protobuf definition by its ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
id
required
string
Example: my-resource-1

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

query Parameters
force
string
Example: force=true

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

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/protos/1",
  • "deleted": "1"
}

List All Protos

Retrieve all stored protobuf definitions.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
name
string

Filter list by name (regex match).

label
string
Example: label=env

Filter list to resources with the given label key.

page
integer >= 1
Default: 1
Example: page=1

Page number (1-based).

page_size
integer [ 10 .. 500 ]
Example: page_size=20

Items per page (10–500). When omitted, no pagination is applied and the full list is returned.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create a Proto

Upload a new protobuf definition with an auto-generated ID.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
query Parameters
ttl
integer >= 1
Example: ttl=3600

Time-to-live in seconds. The resource is automatically removed when it expires.

Request Body schema: application/json
required

Proto configuration body for create / replace / patch.

String ID (string) or Integer ID (integer) (ResourceId)

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

name
string [ 1 .. 256 ] characters

Human-readable name.

desc
string <= 256 characters

Description.

object (Labels)

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

content
required
string [ 1 .. 1048576 ] characters

Protobuf .proto file content as a string.

Responses

Request samples

Content type
application/json
{
  • "content": "syntax = \"proto3\";\n\npackage helloworld;\n\nservice Greeter {\n rpc SayHello (HelloRequest) returns (HelloReply) {}\n}\n\nmessage HelloRequest {\n string name = 1;\n}\n\nmessage HelloReply {\n string message = 1;\n}"
}

Response samples

Content type
application/json
{
  • "key": "/apisix/protos/00000000000000000293",
  • "value": {
    }
}

Schema Validation

The Schema Validation endpoint lets you validate a resource configuration against APISIX's JSON Schema without actually creating the resource.

Use this for dry-run validation in CI/CD pipelines or configuration management tools.

Validate Resource Configuration

Validate a resource configuration against APISIX's JSON Schema without creating the resource. Useful for dry-run validation in CI/CD pipelines.

The {resource} path parameter specifies the resource type (e.g., routes, upstreams, services, etc.).

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
resource
required
string
Enum: "routes" "services" "upstreams" "consumers" "ssls" "plugin_configs" "global_rules" "stream_routes" "protos" "consumer_groups" "credentials"
Example: routes

Resource kind.

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "uri": "/api/v1/*",
  • "upstream": {
    }
}

Response samples

Content type
application/json
Example
{
  • "error_msg": "invalid configuration: property \"uri\" is required"
}

Get the JSON Schema of a built-in resource

Returns the JSON Schema document used internally by APISIX to validate the named resource type.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
resource
required
string
Enum: "routes" "services" "upstreams" "consumers" "ssls" "plugin_configs" "global_rules" "stream_routes" "protos" "consumer_groups" "credentials"
Example: routes

Resource kind.

Responses

Response samples

Content type
application/json
{ }

Get a plugin's JSON Schema (alternative path)

Equivalent to GET /apisix/admin/plugins/{plugin_name}. Provided for symmetry with GET /apisix/admin/schema/{resource}.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
path Parameters
plugin_name
required
string non-empty
Example: limit-count

Plugin name.

Responses

Response samples

Content type
application/json
{ }

Health

Liveness probe.

Liveness probe

Returns 200 OK if the Admin API is reachable. Useful as a Kubernetes liveness probe target. This endpoint does not require authentication.

Responses

Standalone

Endpoints exposed when the deployment uses the YAML config provider (deployment.config_provider: yaml).

Get the standalone configuration

Available only when deployment.config_provider is yaml. Returns the entire current configuration document.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie

Responses

Response samples

Content type
{ }

Replace the standalone configuration

Replaces the entire current configuration. Available only when deployment.config_provider is yaml.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
Request Body schema:
required
object

Responses

Request samples

Content type
{ }

Response samples

Content type
application/json
Example
{
  • "error_msg": "invalid configuration: property \"uri\" is required"
}

Probe standalone configuration availability

Returns 200 OK if the deployment is in YAML provider mode and the configuration endpoint is reachable.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie

Responses

Response samples

Content type
application/json
Example
{
  • "error_msg": "failed to check token",
  • "description": "missing apikey"
}

Validate a standalone configuration without applying it

Validates the supplied configuration document. The current configuration is not modified.

Authorizations:
adminKeyapiKeyQueryapiKeyCookie
Request Body schema:
required
object

Responses

Request samples

Content type
{ }

Response samples

Content type
application/json
Example
{
  • "error_msg": "invalid configuration: property \"uri\" is required"
}