Validate a Configuration Without Applying It

POST /apisix/admin/configs/validate

Interactive request editor loads with JavaScript.

Authorization

X-API-KEY<token>

Admin API key configured in config.yaml under deployment.admin.admin_key. You can also pass the key as a query parameter api_key or cookie x_api_key.

In: header

Request Body

Declarative APISIX configuration to validate. Only the documented resource arrays and their *_conf_version fields are evaluated.

routes?array<|||||||||>

Declarative routes resources to validate.

routes_conf_version?number

Optional routes configuration version. When present, the value must be numeric.

services?array<>

Declarative services resources to validate.

services_conf_version?number

Optional services configuration version. When present, the value must be numeric.

upstreams?array<|>

Declarative upstreams resources to validate.

upstreams_conf_version?number

Optional upstreams configuration version. When present, the value must be numeric.

consumers?array<|>

Declarative consumers resources to validate.

consumers_conf_version?number

Optional consumers configuration version. When present, the value must be numeric.

ssls?array<>

Declarative ssls resources to validate.

ssls_conf_version?number

Optional ssls configuration version. When present, the value must be numeric.

global_rules?array<>

Declarative global_rules resources to validate.

global_rules_conf_version?number

Optional global_rules configuration version. When present, the value must be numeric.

stream_routes?array<>

Declarative stream_routes resources to validate.

stream_routes_conf_version?number

Optional stream_routes configuration version. When present, the value must be numeric.

protos?array<>

Declarative protos resources to validate.

protos_conf_version?number

Optional protos configuration version. When present, the value must be numeric.

plugin_configs?array<>

Declarative plugin_configs resources to validate.

plugin_configs_conf_version?number

Optional plugin_configs configuration version. When present, the value must be numeric.

consumer_groups?array<>

Declarative consumer_groups resources to validate.

consumer_groups_conf_version?number

Optional consumer_groups configuration version. When present, the value must be numeric.

secrets?array<|||>

Declarative secrets resources to validate.

secrets_conf_version?number

Optional secrets configuration version. When present, the value must be numeric.

plugin_metadata?array<>

Declarative plugin_metadata resources to validate.

plugin_metadata_conf_version?number

Optional plugin_metadata configuration version. When present, the value must be numeric.

plugins?array<>

Declarative plugins resources to validate.

plugins_conf_version?number

Optional plugins configuration version. When present, the value must be numeric.

[key: string]?any

Response Body

`application/json`

curl -X POST "http://127.0.0.1:9180/apisix/admin/configs/validate" \  -H "Content-Type: application/json" \  -d '{}'

The supplied configuration passed all applicable checks.

{}

The request body could not be parsed, exceeded 1.5 MiB, or failed one or more configuration checks.

{
  "error_msg": "invalid request body: empty request body"
}

{
  "error_msg": "Configuration validation failed",
  "errors": [
    {
      "resource_type": "routes",
      "resource_id": "route-a",
      "index": 0,
      "error": "property \"uri\" validation failed: wrong type"
    },
    {
      "resource_type": "upstreams",
      "resource_id": "upstream-a",
      "index": 0,
      "error": "missing key"
    }
  ]
}

**Unauthorized** — The API key is missing, invalid, or lacks permission.

{
  "error_msg": "failed to check token",
  "description": "missing apikey"
}

{
  "error_msg": "failed to check token",
  "description": "wrong apikey"
}

{
  "error_msg": "failed to check token",
  "description": "invalid method for role viewer"
}

Complete operation details and schema variants

POST /apisix/admin/configs/validate

Validate a Configuration Without Applying It

Validates a declarative APISIX configuration when the deployment uses either the etcd or yaml configuration provider. The endpoint accepts JSON and YAML request bodies up to 1.5 MiB and uses the normal Admin API authentication.

Validation covers known resource arrays, numeric *_conf_version fields, duplicate resource identifiers, resource JSON Schemas, and plugin check_schema functions. All detected errors are returned together. Cross-resource existence is not checked, so a reference such as an upstream_id can pass even when the referenced resource is absent. The operation does not persist or apply any configuration.

Parameters

Request body

Content type: application/json

routes (array, optional): Declarative routes resources to validate.
routes[].id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
anyOf variant 1: String ID
anyOf variant 2: Integer ID
routes[].name (string, optional): Human-readable name for the route.
routes[].desc (string, optional): Description of what this route does.
routes[].labels (object, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
routes[].create_time (integer, optional): Unix timestamp of creation. Read-only.
routes[].update_time (integer, optional): Unix timestamp of last update. Read-only.
routes[].uri (string, optional): URI path pattern to match. Supports exact match (/api/v1/users) and prefix match (/api/*). Mutually exclusive with uris.
routes[].uris (array, optional): Multiple URI patterns. Mutually exclusive with uri.
routes[].host (string, optional): Single hostname to match against the request's Host header. Supports wildcard prefix (*.example.com). Mutually exclusive with hosts.
routes[].hosts (array, optional): Multiple hostnames to match. Mutually exclusive with host.
routes[].methods (array, optional): HTTP methods allowed on this route. If empty or not set, all methods are allowed.
routes[].remote_addr (string, optional): Single client IP address or CIDR range to match. Mutually exclusive with remote_addrs.
routes[].remote_addrs (array, optional): Multiple client IP addresses or CIDR ranges to match. Mutually exclusive with remote_addr.
routes[].priority (integer, optional): Route priority. When multiple routes match the same request, the one with the highest priority wins.
routes[].vars (array, optional): Custom matching conditions using APISIX expressions. Each condition is an array of [variable, operator, value].
routes[].filter_func (string, optional): Custom Lua function for advanced request matching. Must start with function.
routes[].plugins (object, optional): Plugin configurations as a JSON object. Each key is a plugin name, and the value is that plugin's configuration object.

Example:

{
  "limit-count": {
    "count": 100,
    "time_window": 60
  },
  "key-auth": {}
}