{"openapi":"3.1.0","info":{"title":"Apache APISIX Admin API","description":"The **Apache APISIX Admin API** is a RESTful interface for managing all APISIX gateway resources — routes, upstreams, services, consumers, SSL certificates, plugins, and more.\n\nAPISIX Admin API allows you to dynamically configure the API gateway without restarts. All changes take effect immediately.\n\nUnless API key authentication is explicitly disabled with `deployment.admin.admin_key_required: false`, endpoints require an **API key**. Pass a key configured under `deployment.admin.admin_key` in APISIX's `config.yaml` using the `X-API-KEY` request header.\n\nThe 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`.\n\nTo learn how to configure and operate APISIX, see [Get Started](https://docs.api7.ai/apisix/getting-started/).","version":"3.19.0","contact":{"name":"API7.ai"},"license":{"name":"Apache 2.0","url":"https://www.apache.org/licenses/LICENSE-2.0.html"}},"tags":[{"name":"Routes","description":"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.\n\nA route must include at least a **URI pattern** and one of: an inline `upstream`, an `upstream_id`, a `service_id`, or `plugins`.\n\n**Key Features**\n- Match by URI, host, HTTP method, headers, query parameters, and custom expressions\n- Attach plugins for authentication, rate limiting, transformation, and more\n- Support WebSocket proxying and gRPC transcoding\n- Priority-based routing when multiple routes match\n\nTo learn how to configure routes, see [Routes](https://docs.api7.ai/apisix/key-concepts/routes).","x-displayName":"Routes"},{"name":"Upstreams","description":"An **Upstream** is a virtual host abstraction over a pool of backend service nodes. It defines how APISIX distributes traffic to your backend servers.\n\n**Load Balancing Algorithms**\n- `roundrobin` — Weighted round-robin (default)\n- `chash` — Consistent hashing for session affinity\n- `ewma` — Latency-based selection (exponentially weighted moving average)\n- `least_conn` — Fewest active connections\n\n**Health Checks**\nUpstreams support **active** and **passive** health checks to automatically remove unhealthy nodes from the load balancing pool.\n\nTo learn how to configure upstreams, see [Upstreams](https://docs.api7.ai/apisix/key-concepts/upstreams).","x-displayName":"Upstreams"},{"name":"Services","description":"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.\n\nWhen 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.\n\nTo learn how to configure services, see [Services](https://docs.api7.ai/apisix/key-concepts/services).","x-displayName":"Services"},{"name":"Consumers","description":"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.\n\nEach consumer is uniquely identified by a `username` and can belong to a consumer group.\n\nTo learn how to configure consumers, see [Consumers](https://docs.api7.ai/apisix/key-concepts/consumers).","x-displayName":"Consumers"},{"name":"Consumer Groups","description":"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.\n\nConsumers reference a group via the `group_id` field. Group-level plugins are merged with consumer-level plugins, with consumer-level taking precedence.\n\nTo learn how to configure consumer groups, see [Consumer Groups](https://docs.api7.ai/apisix/key-concepts/consumer-groups).","x-displayName":"Consumer Groups"},{"name":"Credentials","description":"A **Credential** stores authentication configuration associated with a consumer. Each credential holds exactly one authentication plugin (e.g., `key-auth`, `basic-auth`, `jwt-auth`).\n\nCredentials are sub-resources of consumers. A consumer can have multiple credentials, each for a different authentication method.\n\nTo learn how to configure consumer credentials, see [Credentials](https://docs.api7.ai/apisix/key-concepts/credentials).","x-displayName":"Credentials"},{"name":"Plugins","description":"**Plugins** extend APISIX's core functionality with middleware capabilities such as authentication, traffic control, observability, and request/response transformation.\n\nUse these endpoints to query available plugins and their JSON schemas, or to hot-reload plugins without restarting APISIX.\n\nPlugins are attached to routes, services, consumers, or global rules via the `plugins` object.\n\nSee [Plugin Hub](https://docs.api7.ai/hub) for the full list of available plugins.","x-displayName":"Plugins"},{"name":"Plugin Configs","description":"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`.\n\nRoute-level plugins are merged with plugin config plugins, with route-level taking precedence.\n\nTo learn how to configure reusable plugin configurations, see [Plugin Configs](https://docs.api7.ai/apisix/key-concepts/plugin-configs).","x-displayName":"Plugin Configs"},{"name":"Plugin Metadata","description":"**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.\n\nFor example, setting metadata for `http-logger` will affect every route that uses `http-logger`.\n\nTo learn how to configure plugin metadata, see [Plugin Metadata](https://docs.api7.ai/apisix/key-concepts/plugin-metadata).","x-displayName":"Plugin Metadata"},{"name":"Global Rules","description":"A Global Rule applies plugins to incoming requests independently of route and service configuration. For HTTP requests, global and local plugins are interleaved by phase: global `rewrite`, local `rewrite`, global `access`, then local `access`. Plugin priority applies within each phase and scope.\n\nTo learn how to configure global rules, see [Plugin Global Rules](https://docs.api7.ai/apisix/key-concepts/plugin-global-rules).","x-displayName":"Global Rules"},{"name":"Stream Routes","description":"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.\n\nStream routes match traffic by `remote_addr`, `server_addr`, `server_port`, or `sni` (for TLS connections).\n\n**Note:** Stream mode must be enabled in `config.yaml` (`apisix.proxy_mode: stream` or `http&stream`) before creating stream routes.\n\nTo learn how to configure stream routes, see [Stream Routes](https://docs.api7.ai/apisix/key-concepts/stream-routes).","x-displayName":"Stream Routes"},{"name":"SSL Certificates","description":"The **SSL** resource manages TLS certificates for HTTPS termination and mTLS authentication.\n\n**Certificate Types**\n- `server` — Server certificate for HTTPS termination (matched by SNI)\n- `client` — Client certificate for mTLS with upstream services\n\nAPISIX dynamically selects the correct certificate based on the SNI (Server Name Indication) in the TLS handshake. Certificates can be rotated without restart.\n\nTo learn how to configure TLS certificates, see [SSL Certificates](https://docs.api7.ai/apisix/key-concepts/ssl-certificates).","x-displayName":"SSL Certificates"},{"name":"Secrets","description":"The **Secret** resource integrates APISIX with external secret managers (e.g., HashiCorp Vault, AWS Secrets Manager) for dynamic secret retrieval at runtime.\n\nOnce configured, you can reference secrets in plugin configurations using the URI format: `$secret://vault/my-secret/key`.\n\nTo learn how to configure secret managers, see [Secrets](https://docs.api7.ai/apisix/key-concepts/secrets).","x-displayName":"Secrets"},{"name":"Protos","description":"The **Proto** resource stores Protocol Buffer (protobuf) `.proto` file content used by the `grpc-transcode` plugin to convert between HTTP/JSON and gRPC.\n\nUpload your `.proto` definitions here, then reference them by ID in the `grpc-transcode` plugin configuration.\n\nTo learn how to configure gRPC transcoding, see [gRPC Transcode](https://docs.api7.ai/hub/grpc-transcode).","x-displayName":"Protos"},{"name":"Schema Validation","description":"Endpoints for validating one resource or a complete declarative configuration without creating, persisting, or applying it.","x-displayName":"Schema Validation"},{"name":"Health","description":"Liveness probe."},{"name":"Standalone","description":"Endpoints exposed only when the deployment uses the YAML config provider (`deployment.role_data_plane.config_provider: yaml`)."}],"paths":{"/apisix/admin/routes":{"get":{"summary":"List All Routes","description":"Retrieve all configured routes. Supports filtering by `name`, `label`, `uri`, or `filter` expression.\n\nResults include full route configuration and metadata (creation/update timestamps).","tags":["Routes"],"parameters":[{"$ref":"#/components/parameters/NameFilter"},{"$ref":"#/components/parameters/LabelFilter"},{"$ref":"#/components/parameters/UriFilter"},{"$ref":"#/components/parameters/FilterExpr"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteListEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"total":1,"list":[{"createdIndex":203,"key":"/apisix/routes/1","value":{"remote_addrs":["127.0.0.1"],"desc":"desc","name":"route-test","priority":0,"vars":[["http_user","==","ios"]],"update_time":1684490006,"create_time":1684490006,"id":"1","plugins":{"limit-count":{"show_limit_quota_header":true,"policy":"local","count":2,"allow_degradation":false,"rejected_code":503,"time_window":60,"key_type":"var","key":"remote_addr"}},"status":1,"timeout":{"read":3,"connect":3,"send":3},"uri":"/ip","upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"httpbin.org:80":1},"type":"roundrobin","scheme":"http"},"methods":["GET","POST"],"hosts":["a.com","b.com"]},"modifiedIndex":203}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listRoutes","x-codeSamples":[{"lang":"cURL","label":"cURL","source":"curl -i http://127.0.0.1:9180/apisix/admin/routes \\\n  -H 'X-API-KEY: your-api-key'"}]},"post":{"summary":"Create a Route","description":"Create a new route with an auto-generated ID.\n\nA route must include at least a `uri` and one of: `upstream` (inline), `upstream_id`, `service_id`, or `plugins`.","tags":["Routes"],"parameters":[{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/RouteUpsertPostCollection"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"value":{"desc":"desc","name":"route-name","update_time":1684490245,"priority":0,"id":"00000000000000000206","status":1,"create_time":1684490245,"uri":"/ip","upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"httpbin.org:80":1},"type":"roundrobin","scheme":"http"},"methods":["GET","POST"],"hosts":["a.com","b.com"]},"key":"/apisix/routes/00000000000000000206"}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createRoute","x-codeSamples":[{"lang":"cURL","label":"cURL","source":"curl -i http://127.0.0.1:9180/apisix/admin/routes \\\n  -H 'X-API-KEY: your-api-key' \\\n  -H 'Content-Type: application/json' \\\n  -X POST -d '{\n    \"uri\": \"/api/v1/users/*\",\n    \"upstream\": {\n      \"type\": \"roundrobin\",\n      \"nodes\": {\"10.0.0.1:8080\": 1}\n    }\n  }'"}]}},"/apisix/admin/routes/{id}":{"put":{"summary":"Create or Replace a Route","description":"Create a new route with a specified ID, or fully replace an existing route.\n\n**Note:** This is a full replacement — all fields must be provided. Use `PATCH` for partial updates.","tags":["Routes"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/RouteUpsertPutId"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"value":{"remote_addrs":["127.0.0.1"],"desc":"desc","name":"route-test","priority":0,"plugins":{"limit-count":{"show_limit_quota_header":true,"policy":"local","count":2,"key":"remote_addr","rejected_code":503,"time_window":60,"key_type":"var","allow_degradation":false}},"vars":[["http_user","==","ios"]],"id":"1","status":1,"uri":"/ip","timeout":{"connect":3,"read":3,"send":3},"upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"httpbin.org:80":1},"type":"roundrobin","scheme":"http"},"methods":["GET","POST"],"hosts":["a.com","b.com"]},"key":"/apisix/routes/1"}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createRouteById","x-codeSamples":[{"lang":"cURL","label":"cURL","source":"curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \\\n  -H 'X-API-KEY: your-api-key' \\\n  -H 'Content-Type: application/json' \\\n  -X PUT -d '{\n    \"uri\": \"/api/v1/payments\",\n    \"methods\": [\"POST\"],\n    \"upstream\": {\n      \"type\": \"roundrobin\",\n      \"nodes\": {\"payments-service:8080\": 1}\n    }\n  }'"}]},"get":{"summary":"Get a Route","description":"Retrieve a single route by its ID.","tags":["Routes"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"createdIndex":203,"key":"/apisix/routes/1","value":{"remote_addrs":["127.0.0.1"],"desc":"desc","name":"route-test","priority":0,"vars":[["http_user","==","ios"]],"update_time":1684490006,"create_time":1684490006,"id":"1","plugins":{"limit-count":{"show_limit_quota_header":true,"policy":"local","count":2,"allow_degradation":false,"rejected_code":503,"time_window":60,"key_type":"var","key":"remote_addr"}},"status":1,"timeout":{"read":3,"connect":3,"send":3},"uri":"/ip","upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"httpbin.org:80":1},"type":"roundrobin","scheme":"http"},"methods":["GET","POST"],"hosts":["a.com","b.com"]},"modifiedIndex":203}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"getRoute","x-codeSamples":[{"lang":"cURL","label":"cURL","source":"curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \\\n  -H 'X-API-KEY: your-api-key'"}]},"patch":{"summary":"Update a Route (Partial)","description":"Partially update a route's configuration. Only the fields included in the request body are modified; all other fields remain unchanged.\n\n**Tip:** Use this to update a single field (e.g., change the upstream) without resending the entire route configuration.","tags":["Routes"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/RouteUpsertPatchId"},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteEnvelope"},"examples":{"1":{"summary":"Update Upstream Node To The Route","value":{"value":{"remote_addrs":["127.0.0.1"],"desc":"desc","name":"route-test","priority":0,"vars":[["http_user","==","ios"]],"update_time":1684490363,"create_time":1684490006,"id":"1","plugins":{"limit-count":{"show_limit_quota_header":true,"policy":"local","count":2,"allow_degradation":false,"rejected_code":503,"time_window":60,"key_type":"var","key":"remote_addr"}},"status":1,"timeout":{"read":3,"connect":3,"send":3},"uri":"/ip","upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"httpbin.org:80":1,"127.0.0.1:1981":1},"type":"roundrobin","scheme":"http"},"methods":["GET","POST"],"hosts":["a.com","b.com"]},"key":"/apisix/routes/1"}},"2":{"summary":"Delete An Upstream Node For The Route","value":{"value":{"remote_addrs":["127.0.0.1"],"desc":"desc","name":"route-test","vars":[["http_user","==","ios"]],"priority":0,"update_time":1684490476,"create_time":1684490006,"plugins":{"limit-count":{"show_limit_quota_header":true,"policy":"local","count":2,"key":"remote_addr","rejected_code":503,"time_window":60,"key_type":"var","allow_degradation":false}},"id":"1","status":1,"uri":"/ip","timeout":{"connect":3,"read":3,"send":3},"upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"httpbin.org:80":1},"type":"roundrobin","scheme":"http"},"methods":["GET","POST"],"hosts":["a.com","b.com"]},"key":"/apisix/routes/1"}},"3":{"summary":"Disable Route","value":{"value":{"remote_addrs":["127.0.0.1"],"vars":[["http_user","==","ios"]],"name":"route-test","desc":"desc","priority":0,"update_time":1684490503,"create_time":1684490006,"id":"1","plugins":{"limit-count":{"show_limit_quota_header":true,"policy":"local","count":2,"allow_degradation":false,"rejected_code":503,"time_window":60,"key_type":"var","key":"remote_addr"}},"status":0,"timeout":{"read":3,"connect":3,"send":3},"uri":"/ip","upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"httpbin.org:80":1},"type":"roundrobin","scheme":"http"},"methods":["GET","POST"],"hosts":["a.com","b.com"]},"key":"/apisix/routes/1"}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"updateRoute"},"delete":{"summary":"Delete a Route","description":"Delete a route by its ID. This action is irreversible.","tags":["Routes"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"name":"force","in":"query","description":"Delete resource by force even if the resource is in use.","required":false,"example":"true","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"Unique key identifier for this route in the data store.","type":"string"},"deleted":{"description":"The ID of the successfully deleted route.","type":"string"}}},"examples":{"1":{"summary":"Successful Example","value":{"deleted":"1","key":"/apisix/routes/1"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"deleteRoute","x-codeSamples":[{"lang":"cURL","label":"cURL","source":"curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \\\n  -H 'X-API-KEY: your-api-key' -X DELETE"}]}},"/apisix/admin/services":{"get":{"summary":"List All Services","description":"Retrieve all configured services.","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/NameFilter"},{"$ref":"#/components/parameters/LabelFilter"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceListEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"total":1,"list":[{"createdIndex":117,"key":"/apisix/services/1","value":{"enable_websocket":true,"name":"service-test","update_time":1684288908,"create_time":1684287870,"id":"1","desc":"hello world","upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"127.0.0.1:1980":1},"type":"roundrobin","scheme":"http"},"plugins":{"limit-count":{"show_limit_quota_header":true,"policy":"local","count":2,"key":"remote_addr","rejected_code":503,"time_window":60,"key_type":"var","allow_degradation":false}},"hosts":["foo.com"]},"modifiedIndex":118}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listServices"},"post":{"summary":"Create a Service","description":"Create a new service with an auto-generated ID.","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/ServiceUpsertPostCollection"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"value":{"enable_websocket":true,"name":"service-test","update_time":1684491069,"create_time":1684491069,"plugins":{},"id":"00000000000000000218","upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"127.0.0.1:1980":1},"type":"roundrobin","scheme":"http"},"desc":"hello world","hosts":["foo.com"]},"key":"/apisix/services/00000000000000000218"}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createService"}},"/apisix/admin/services/{id}":{"get":{"summary":"Get a Service","description":"Retrieve a single service by its ID.","tags":["Services"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"createdIndex":117,"key":"/apisix/services/1","value":{"enable_websocket":true,"name":"service-test","update_time":1684490934,"create_time":1684287870,"plugins":{"limit-count":{"show_limit_quota_header":true,"policy":"local","count":2,"allow_degradation":false,"rejected_code":503,"time_window":60,"key_type":"var","key":"remote_addr"}},"desc":"hello world","upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"127.0.0.1:1980":1},"type":"roundrobin","scheme":"http"},"id":"1","hosts":["foo.com"]},"modifiedIndex":216}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"getService"},"put":{"summary":"Create or Replace a Service","description":"Create a new service with a specified ID, or fully replace an existing service.","tags":["Services"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/ServiceUpsertPutId"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"value":{"desc":"hello world","name":"service-test","update_time":1684491005,"create_time":1684287870,"plugins":{"limit-count":{"show_limit_quota_header":true,"policy":"local","count":2,"key":"remote_addr","rejected_code":503,"time_window":60,"key_type":"var","allow_degradation":false}},"id":"1","upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"127.0.0.1:1980":1},"type":"roundrobin","scheme":"http"},"enable_websocket":true,"hosts":["foo.com"]},"key":"/apisix/services/1"}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createServiceById"},"patch":{"summary":"Update a Service (Partial)","description":"Partially update a service's configuration.","tags":["Services"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/ServiceUpsertPatchId"},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceEnvelope"},"examples":{"1":{"summary":"Update Upstream Node To The Service","value":{"value":{"upstream":{"scheme":"http","nodes":{"127.0.0.1:1981":1,"127.0.0.1:1980":1},"type":"roundrobin","hash_on":"vars","pass_host":"pass"},"create_time":1684142130,"enable_websocket":true,"id":"1","update_time":1684142459,"hosts":["foo.com"],"name":"service-test","plugins":{},"desc":"hello world"},"key":"/apisix/services/1"}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"updateService"},"delete":{"summary":"Delete a Service","description":"Delete a service by its ID.","tags":["Services"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"name":"force","in":"query","description":"Delete resource by force even if the resource is in use.","required":false,"example":"true","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"description":"The ID of the successfully deleted service.","type":"string"},"key":{"description":"Unique key identifier for this service.","type":"string"}}},"examples":{"1":{"summary":"Successful Example","value":{"deleted":"1","key":"/apisix/services/1"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"deleteService"}},"/apisix/admin/services/{service_id}/graphql_cost_decorations":{"parameters":[{"name":"service_id","in":"path","required":true,"description":"ID of the owning service.","schema":{"$ref":"#/components/schemas/ResourceId"}}],"get":{"tags":["Services"],"summary":"List GraphQL Cost Decorations","description":"List decorations owned by this service. A service with no decorations returns 404 rather than an empty list.","operationId":"listGraphQLCostDecorations","parameters":[{"$ref":"#/components/parameters/NameFilter"},{"$ref":"#/components/parameters/LabelFilter"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Decoration list scoped to a service.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphQLCostDecorationListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No decorations were found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The configuration store is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Services"],"summary":"Create a GraphQL Cost Decoration","description":"Create a decoration with an automatically generated ID. The service must exist. Ownership is taken from the URL; omit `service_id` in the body. Keep `field_path` unique within a service, and serialize concurrent writes for the service.","operationId":"createGraphQLCostDecoration","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphQLCostDecorationCreate"},"example":{"field_path":"Query.products","add_value":1,"mul_value":1,"mul_arguments":["first"]}}}},"responses":{"201":{"description":"Decoration created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphQLCostDecorationEnvelope"}}}},"400":{"description":"Invalid configuration, conflicting service ID, or duplicate `field_path`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"The owning service does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The configuration store is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/apisix/admin/services/{service_id}/graphql_cost_decorations/{decoration_id}":{"parameters":[{"name":"service_id","in":"path","required":true,"description":"ID of the owning service.","schema":{"$ref":"#/components/schemas/ResourceId"}},{"name":"decoration_id","in":"path","required":true,"description":"Decoration ID, unique within the service.","schema":{"$ref":"#/components/schemas/ResourceId"}}],"get":{"tags":["Services"],"summary":"Get a GraphQL Cost Decoration","operationId":"getGraphQLCostDecoration","responses":{"200":{"description":"Decoration found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphQLCostDecorationEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"The decoration does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The configuration store is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[]},"put":{"tags":["Services"],"summary":"Create or Replace a GraphQL Cost Decoration","description":"Replace the complete decoration or create it if absent. The service must exist. Ownership is taken from the URL; a conflicting `service_id` in the body is rejected. Keep `field_path` unique within a service, and serialize concurrent writes for the service.","operationId":"replaceGraphQLCostDecoration","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphQLCostDecoration"},"example":{"field_path":"Query.products","add_value":1,"mul_value":1,"mul_arguments":["first"]}}}},"responses":{"200":{"description":"Decoration replaced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphQLCostDecorationEnvelope"}}}},"201":{"description":"Decoration created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphQLCostDecorationEnvelope"}}}},"400":{"description":"Invalid configuration, conflicting service ID, or duplicate `field_path`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"The owning service does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The configuration store is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Services"],"summary":"Update a GraphQL Cost Decoration","description":"Merge fields into an existing decoration. `service_id` cannot be patched, even to its existing value. A changed `field_path` must not duplicate another decoration on the service. JSON subpath patching is not supported for this subresource.","operationId":"updateGraphQLCostDecoration","requestBody":{"$ref":"#/components/requestBodies/GraphQLCostDecorationPatchBody"},"responses":{"200":{"description":"Decoration updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphQLCostDecorationEnvelope"}}}},"400":{"description":"Invalid configuration, conflicting service ID, or duplicate `field_path`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"The decoration does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The configuration store is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[]},"delete":{"tags":["Services"],"summary":"Delete a GraphQL Cost Decoration","operationId":"deleteGraphQLCostDecoration","responses":{"200":{"description":"Decoration deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"The decoration does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The configuration store is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"$ref":"#/components/parameters/Force"}]}},"/apisix/admin/consumers":{"put":{"summary":"Create or Update a Consumer","description":"Create a new consumer or update an existing one. The consumer is identified by `username` in the request body.","tags":["Consumers"],"parameters":[{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/ConsumerUpsertPutCollection"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"Unique key identifier for this consumer.","type":"string"},"value":{"description":"Consumer values.","properties":{"plugins":{"description":"Key-value pairs of plugins and their configurations on the object.","type":"object","properties":{}},"username":{"description":"The unique identifier of the consumer.","type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9_-]+$"},"labels":{"type":"object","patternProperties":{".*":{"minLength":1,"maxLength":64,"pattern":"^\\S+$","type":"string","description":"Value of label."}},"description":"Key-value pairs to specify attributes.","properties":{}},"desc":{"description":"Consumer description.","maxLength":256,"type":"string"},"group_id":{"description":"Consumer group ID.","anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$"},{"minimum":1,"type":"integer"}]},"create_time":{"description":"Creation time of the consumer.","type":"integer"}},"type":"object"}}},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/consumers/jack","value":{"plugins":{"limit-count":{"time_window":60,"rejected_code":503,"key":"remote_addr","key_type":"var","count":2,"show_limit_quota_header":true,"allow_degradation":false,"policy":"local"}},"username":"jack","create_time":1683164776,"update_time":1684289832}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createConsumer","x-codeSamples":[{"lang":"cURL","label":"cURL","source":"curl -i http://127.0.0.1:9180/apisix/admin/consumers \\\n  -H 'X-API-KEY: your-api-key' \\\n  -H 'Content-Type: application/json' \\\n  -X PUT -d '{\n    \"username\": \"my-app\",\n    \"plugins\": {\n      \"key-auth\": {\"key\": \"app-secret-key-123\"}\n    }\n  }'"}]},"get":{"summary":"List All Consumers","description":"Retrieve all configured consumers.","tags":["Consumers"],"parameters":[{"$ref":"#/components/parameters/LabelFilter"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerListEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"list":[{"value":{"plugins":{"limit-count":{"rejected_code":503,"time_window":60,"key":"remote_addr","key_type":"var","count":2,"allow_degradation":false,"show_limit_quota_header":true,"policy":"local"}},"username":"jack","create_time":1683164776,"update_time":1684289832},"key":"/apisix/consumers/jack","modifiedIndex":119,"createdIndex":17}],"total":1}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listConsumers"}},"/apisix/admin/consumers/{username}":{"get":{"summary":"Get a Consumer","description":"Retrieve a single consumer by username.","tags":["Consumers"],"parameters":[{"$ref":"#/components/parameters/UsernameInPath"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"value":{"plugins":{"limit-count":{"rejected_code":503,"time_window":60,"key":"remote_addr","key_type":"var","count":2,"allow_degradation":false,"show_limit_quota_header":true,"policy":"local"}},"username":"jack","create_time":1683164776,"update_time":1684289832},"key":"/apisix/consumers/jack","modifiedIndex":119,"createdIndex":17}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"getConsumer"},"delete":{"summary":"Delete a Consumer","description":"Delete a consumer by username. This also deletes all associated credentials.","tags":["Consumers"],"parameters":[{"$ref":"#/components/parameters/UsernameInPath"},{"name":"force","in":"query","description":"Delete resource by force even if the resource is in use.","required":false,"example":"true","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"Unique key identifier for this consumer in the data store.","type":"string"},"deleted":{"description":"The ID of the successfully deleted consumer.","type":"string"}}},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/consumers/jack","deleted":"1"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"deleteConsumer"}},"/apisix/admin/upstreams":{"get":{"summary":"List All Upstreams","description":"Retrieve all configured upstreams.","tags":["Upstreams"],"parameters":[{"$ref":"#/components/parameters/NameFilter"},{"$ref":"#/components/parameters/LabelFilter"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpstreamListEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"list":[{"value":{"timeout":{"send":15,"read":15,"connect":15},"desc":"desc","id":"1","create_time":1684290697,"retries":1,"pass_host":"pass","update_time":1684291419,"type":"roundrobin","name":"upstream-for-test","hash_on":"vars","nodes":{"httpbin.org:443":1},"scheme":"https"},"key":"/apisix/upstreams/1","modifiedIndex":126,"createdIndex":121},{"value":{"timeout":{"send":15,"read":15,"connect":15},"desc":"desc","id":"2","create_time":1684291436,"retries":1,"pass_host":"pass","update_time":1684291436,"type":"roundrobin","name":"upstream-for-test","hash_on":"vars","nodes":{"mock.api7.ai:443":1},"scheme":"https"},"key":"/apisix/upstreams/2","modifiedIndex":127,"createdIndex":127}],"total":2}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listUpstreams"},"post":{"summary":"Create an Upstream","description":"Create a new upstream with an auto-generated ID.","tags":["Upstreams"],"parameters":[{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/UpstreamUpsertPostCollection"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpstreamEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/upstreams/00000000000000000128","value":{"timeout":{"send":15,"read":15,"connect":15},"desc":"desc","id":"00000000000000000128","create_time":1684291897,"retries":1,"pass_host":"pass","update_time":1684291897,"type":"roundrobin","name":"upstream-for-test","hash_on":"vars","nodes":{"127.0.0.1:1980":1},"scheme":"http"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createUpstream"}},"/apisix/admin/upstreams/{id}":{"put":{"summary":"Create or Replace an Upstream","description":"Create a new upstream with a specified ID, or fully replace an existing upstream.","tags":["Upstreams"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/UpstreamUpsertPutId"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpstreamEnvelope"},"examples":{"1":{"summary":"Create an Upstream by ID","value":{"key":"/apisix/upstreams/1","value":{"timeout":{"send":15,"read":15,"connect":15},"desc":"desc","id":"1","create_time":1684290697,"retries":1,"pass_host":"pass","update_time":1684290697,"type":"roundrobin","name":"upstream-for-test","hash_on":"vars","nodes":{"127.0.0.1:1980":1},"scheme":"http"}}},"2":{"summary":"Create HTTPS Upstream","value":{"key":"/apisix/upstreams/1","value":{"timeout":{"send":15,"read":15,"connect":15},"desc":"desc","id":"1","create_time":1684290697,"retries":1,"pass_host":"pass","update_time":1684291419,"type":"roundrobin","name":"upstream-for-test","hash_on":"vars","nodes":{"httpbin.org:443":1},"scheme":"https"}}},"3":{"summary":"Enable Health Check","value":{"key":"/apisix/upstreams/1","value":{"hash_on":"vars","desc":"desc","id":"1","create_time":1684292372,"checks":{"passive":{"type":"http","healthy":{"http_statuses":[200,201],"successes":3},"unhealthy":{"timeouts":7,"http_statuses":[500],"http_failures":3,"tcp_failures":3}},"active":{"host":"foo.com","concurrency":10,"http_path":"/status","https_verify_certificate":true,"type":"http","req_headers":["User-Agent: curl/7.29.0"],"healthy":{"successes":1,"http_statuses":[200,302],"interval":2},"timeout":5,"unhealthy":{"timeouts":3,"http_statuses":[429,404,500,501,502,503,504,505],"interval":1,"http_failures":2,"tcp_failures":2}}},"pass_host":"pass","update_time":1684292372,"type":"roundrobin","name":"upstream-for-test","retries":1,"nodes":{"127.0.0.1:1980":1,"127.0.0.1:1970":1},"scheme":"http"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createUpstreamById"},"patch":{"summary":"Update an Upstream (Partial)","description":"Partially update an upstream's configuration.","tags":["Upstreams"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/UpstreamUpsertPatchId"},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpstreamEnvelope"},"examples":{"1":{"summary":"Add Node for Upstream","value":{"key":"/apisix/upstreams/1","value":{"timeout":{"send":15,"read":15,"connect":15},"desc":"desc","id":"1","create_time":1684290697,"retries":1,"pass_host":"pass","update_time":1684291001,"type":"roundrobin","name":"upstream-for-test","hash_on":"vars","nodes":{"127.0.0.1:1981":1,"127.0.0.1:1980":1},"scheme":"http"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"updateUpstream"},"get":{"summary":"Get an Upstream","description":"Retrieve a single upstream by its ID.","tags":["Upstreams"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpstreamEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"value":{"timeout":{"send":15,"read":15,"connect":15},"desc":"desc","id":"1","create_time":1684290697,"retries":1,"pass_host":"pass","update_time":1684291419,"type":"roundrobin","name":"upstream-for-test","hash_on":"vars","nodes":{"httpbin.org:443":1},"scheme":"https"},"key":"/apisix/upstreams/1","modifiedIndex":126,"createdIndex":121}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"getUpstream"},"delete":{"summary":"Delete an Upstream","description":"Delete an upstream by its ID. Fails if the upstream is still referenced by a route or service.","tags":["Upstreams"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"name":"force","in":"query","description":"Delete resource by force even if the resource is in use.","required":false,"example":"true","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"Unique key identifier for this upstream in the data store.","type":"string"},"deleted":{"description":"The ID of the successfully deleted upstream","type":"string"}}},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/upstreams/1","deleted":"1"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"deleteUpstream"}},"/apisix/admin/ssls":{"get":{"summary":"List All SSL Certificates","description":"Retrieve all configured SSL certificates. Private keys are **not** included in the response for security.","tags":["SSL Certificates"],"parameters":[{"$ref":"#/components/parameters/LabelFilter"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SSLListEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"list":[{"value":{"type":"server","key":"-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDh5cAWYXAMPLEbe\nfakekeyForOpenAPISpecPlaceholderOnlyDoNotUseForRealKeysNopeNopeNo\npeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNo\npeNopeNopeNopeNopeNopeNope==\n-----END PRIVATE KEY-----\n","snis":["test.com"],"id":"1","create_time":1684373523,"status":1,"cert":"-----BEGIN CERTIFICATE-----\nMIIDazCCAlOgAwIBAgIUJ9hQk3kXgZeZpY/m/0V6RmH1AbcwDQYJKoZIhvcNAQEL\nBQAwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM\nGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMB4XDTI1MDEwMTAwMDAwMFoXDTM1\nMDEwMTAwMDAwMFowRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUx\nITAfBgNVBAoMGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4eXAMPLEcaPUBLIcfakeforopeNAPIspecON\nLYexampleCAcontentsoExpandedFakeKeyMaterial==\n-----END CERTIFICATE-----\n","update_time":1684373523},"key":"/apisix/ssls/1","modifiedIndex":133,"createdIndex":133}],"total":1}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listSSLCertificates"},"post":{"summary":"Create an SSL Certificate","description":"Upload a new SSL certificate with an auto-generated ID.","tags":["SSL Certificates"],"parameters":[{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/SslUpsertPostCollection"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SSLEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/ssls/00000000000000000134","value":{"type":"server","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","id":"00000000000000000134","create_time":1684374944,"status":1,"snis":["test.com"],"update_time":1684374944}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createSSLCertificate"}},"/apisix/admin/ssls/{id}":{"put":{"summary":"Create or Replace an SSL Certificate","description":"Upload a new SSL certificate with a specified ID, or replace an existing one.","tags":["SSL Certificates"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/SslUpsertPutId"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SSLEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/ssls/1","value":{"type":"server","key":"-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDh5cAWYXAMPLEbe\nfakekeyForOpenAPISpecPlaceholderOnlyDoNotUseForRealKeysNopeNopeNo\npeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNo\npeNopeNopeNopeNopeNopeNope==\n-----END PRIVATE KEY-----\n","snis":["test.com"],"id":"1","create_time":1684373523,"status":1,"cert":"-----BEGIN CERTIFICATE-----\nMIIDazCCAlOgAwIBAgIUJ9hQk3kXgZeZpY/m/0V6RmH1AbcwDQYJKoZIhvcNAQEL\nBQAwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM\nGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMB4XDTI1MDEwMTAwMDAwMFoXDTM1\nMDEwMTAwMDAwMFowRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUx\nITAfBgNVBAoMGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4eXAMPLEcaPUBLIcfakeforopeNAPIspecON\nLYexampleCAcontentsoExpandedFakeKeyMaterial==\n-----END CERTIFICATE-----\n","update_time":1684373523}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createSSLCertificateById"},"get":{"summary":"Get an SSL Certificate","description":"Retrieve a single SSL certificate by its ID. The private key is **not** included in the response.","tags":["SSL Certificates"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SSLEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"value":{"type":"server","snis":["test.com"],"id":"1","create_time":1684373523,"status":1,"cert":"-----BEGIN CERTIFICATE-----\nMIIDazCCAlOgAwIBAgIUJ9hQk3kXgZeZpY/m/0V6RmH1AbcwDQYJKoZIhvcNAQEL\nBQAwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM\nGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMB4XDTI1MDEwMTAwMDAwMFoXDTM1\nMDEwMTAwMDAwMFowRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUx\nITAfBgNVBAoMGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4eXAMPLEcaPUBLIcfakeforopeNAPIspecON\nLYexampleCAcontentsoExpandedFakeKeyMaterial==\n-----END CERTIFICATE-----\n","update_time":1684373523},"key":"/apisix/ssls/1","modifiedIndex":133,"createdIndex":133}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"getSSLCertificate"},"patch":{"summary":"Update an SSL Certificate (Partial)","description":"Partially update an SSL certificate's configuration. Only the fields included in the request body are modified; all other fields remain unchanged.","tags":["SSL Certificates"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/SslUpsertPatchId"},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SSLEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"updateSSLCertificate"},"delete":{"summary":"Delete an SSL Certificate","description":"Delete an SSL certificate by its ID.","tags":["SSL Certificates"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"name":"force","in":"query","description":"Delete resource by force even if the resource is in use.","required":false,"example":"true","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"The storage key or path identifier for the SSL object in the data store.","type":"string"},"deleted":{"description":"The ID of the successfully deleted SSL.","type":"string"}}},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/ssls/00000000000000000134","deleted":"1"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"deleteSSLCertificate"}},"/apisix/admin/global_rules":{"get":{"summary":"List All Global Rules","description":"Retrieve all configured global rules.","tags":["Global Rules"],"parameters":[{"$ref":"#/components/parameters/NameFilter"},{"$ref":"#/components/parameters/LabelFilter"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalRuleListEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"list":[{"value":{"plugins":{"limit-count":{"rejected_code":503,"time_window":60,"key":"remote_addr","key_type":"var","count":2,"allow_degradation":false,"show_limit_quota_header":true,"policy":"local"}},"update_time":1684375502,"create_time":1684375502,"id":"1"},"key":"/apisix/global_rules/1","modifiedIndex":137,"createdIndex":137}],"total":1}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listGlobalRules"}},"/apisix/admin/global_rules/{id}":{"put":{"summary":"Create or Replace a Global Rule","description":"Create a new global rule with a specified ID, or fully replace an existing one.","tags":["Global Rules"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/GlobalRuleUpsertPutId"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalRuleEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/global_rules/1","value":{"plugins":{"limit-count":{"time_window":60,"rejected_code":503,"key":"remote_addr","key_type":"var","count":2,"show_limit_quota_header":true,"allow_degradation":false,"policy":"local"}},"id":"1","create_time":1684375502,"update_time":1684375502}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createGlobalRuleById"},"get":{"summary":"Get a Global Rule","description":"Retrieve a single global rule by its ID.","tags":["Global Rules"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalRuleEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"value":{"plugins":{"limit-count":{"rejected_code":503,"time_window":60,"key":"remote_addr","key_type":"var","count":2,"allow_degradation":false,"show_limit_quota_header":true,"policy":"local"}},"update_time":1684375502,"create_time":1684375502,"id":"1"},"key":"/apisix/global_rules/1","modifiedIndex":137,"createdIndex":137}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"getGlobalRule"},"patch":{"summary":"Update a Global Rule (Partial)","description":"Partially update a global rule's configuration.","tags":["Global Rules"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/GlobalRuleUpsertPatchId"},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalRuleEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/global_rules/1","value":{"plugins":{"limit-count":{"rejected_code":503,"time_window":60,"key":"remote_addr","key_type":"var","count":3,"allow_degradation":false,"show_limit_quota_header":true,"policy":"local"}},"update_time":1684376614,"create_time":1684375502,"id":"1"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"updateGlobalRule"},"delete":{"summary":"Delete a Global Rule","description":"Delete a global rule by its ID.","tags":["Global Rules"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"name":"force","in":"query","description":"Delete resource by force even if the resource is in use.","required":false,"example":"true","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"The storage key or path identifier for the global rule.","type":"string"},"deleted":{"description":"The ID of the successfully deleted global rule.","type":"string"}}},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/global_rules/1","deleted":"1"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"deleteGlobalRule"}},"/apisix/admin/consumer_groups":{"get":{"summary":"List All Consumer Groups","description":"Retrieve all configured consumer groups.","tags":["Consumer Groups"],"parameters":[{"$ref":"#/components/parameters/NameFilter"},{"$ref":"#/components/parameters/LabelFilter"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerGroupListEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"list":[{"value":{"plugins":{"limit-count":{"allow_degradation":false,"count":2,"group":"consumer_group_name","time_window":60,"show_limit_quota_header":true,"key":"remote_addr","rejected_code":503,"key_type":"var","policy":"local"}},"desc":"desc","id":"company_a","create_time":1684377809,"update_time":1684378459},"key":"/apisix/consumer_groups/company_a","modifiedIndex":144,"createdIndex":143}],"total":1}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listConsumerGroups"}},"/apisix/admin/consumer_groups/{id}":{"put":{"summary":"Create or Replace a Consumer Group","description":"Create a new consumer group with a specified ID, or fully replace an existing one.","tags":["Consumer Groups"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/ConsumerGroupUpsertPutId"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerGroupEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/consumer_groups/company_a","value":{"plugins":{"limit-count":{"allow_degradation":false,"count":2,"group":"company_a","time_window":60,"key":"remote_addr","key_type":"var","show_limit_quota_header":true,"rejected_code":503,"policy":"local"}},"desc":"desc","id":"company_a","create_time":1684377809,"update_time":1684378459}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createConsumerGroupById"},"get":{"summary":"Get a Consumer Group","description":"Retrieve a single consumer group by its ID.","tags":["Consumer Groups"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerGroupEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"value":{"plugins":{"limit-count":{"allow_degradation":false,"count":2,"group":"consumer_group_name","time_window":60,"show_limit_quota_header":true,"key":"remote_addr","rejected_code":503,"key_type":"var","policy":"local"}},"desc":"desc","id":"company_a","create_time":1684377809,"update_time":1684378459},"key":"/apisix/consumer_groups/company_a","modifiedIndex":144,"createdIndex":143}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"getConsumerGroup"},"patch":{"summary":"Update a Consumer Group (Partial)","description":"Partially update a consumer group's configuration.","tags":["Consumer Groups"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/ConsumerGroupUpsertPatchId"},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerGroupEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/consumer_groups/company_a","value":{"plugins":{"limit-count":{"allow_degradation":false,"count":2,"group":"consumer_group_name","time_window":60,"show_limit_quota_header":true,"key":"remote_addr","rejected_code":503,"key_type":"var","policy":"local"},"prometheus":{"prefer_name":false}},"desc":"desc","id":"company_a","create_time":1684377809,"update_time":1684379208}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"updateConsumerGroup"},"delete":{"summary":"Delete a Consumer Group","description":"Delete a consumer group by its ID.","tags":["Consumer Groups"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"name":"force","in":"query","description":"Delete resource by force even if the resource is in use.","required":false,"example":"true","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"The storage key or path identifier for the consumer group.","type":"string"},"deleted":{"description":"The ID of the successfully deleted consumer group.","type":"string"}}},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/consumer_groups/company_a","deleted":"1"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"deleteConsumerGroup"}},"/apisix/admin/plugin_configs":{"get":{"summary":"List All Plugin Configs","description":"Retrieve all configured plugin configs.","tags":["Plugin Configs"],"parameters":[{"$ref":"#/components/parameters/NameFilter"},{"$ref":"#/components/parameters/LabelFilter"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginConfigListEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"list":[{"value":{"plugins":{"limit-count":{"rejected_code":503,"time_window":60,"key":"remote_addr","key_type":"var","count":2,"allow_degradation":false,"show_limit_quota_header":true,"policy":"local"}},"desc":"desc","id":"1","create_time":1684380007,"update_time":1684380034},"key":"/apisix/plugin_configs/1","modifiedIndex":151,"createdIndex":150}],"total":1}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listPluginConfigs"}},"/apisix/admin/plugin_configs/{id}":{"put":{"summary":"Create or Replace a Plugin Config","description":"Create a new plugin config with a specified ID, or fully replace an existing one.","tags":["Plugin Configs"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/PluginConfigUpsertPutId"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginConfigEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/plugin_configs/1","value":{"plugins":{"limit-count":{"time_window":60,"rejected_code":503,"key":"remote_addr","key_type":"var","count":2,"show_limit_quota_header":true,"allow_degradation":false,"policy":"local"}},"desc":"desc","id":"1","create_time":1684380007,"update_time":1684380034}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createPluginConfigById"},"get":{"summary":"Get a Plugin Config","description":"Retrieve a single plugin config by its ID.","tags":["Plugin Configs"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginConfigEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"value":{"plugins":{"limit-count":{"rejected_code":503,"time_window":60,"key":"remote_addr","key_type":"var","count":2,"allow_degradation":false,"show_limit_quota_header":true,"policy":"local"}},"desc":"desc","id":"1","create_time":1684380007,"update_time":1684380034},"key":"/apisix/plugin_configs/1","modifiedIndex":151,"createdIndex":150}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"getPluginConfig"},"patch":{"summary":"Update a Plugin Config (Partial)","description":"Partially update a plugin config's configuration.","tags":["Plugin Configs"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/PluginConfigUpsertPatchId"},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginConfigEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/plugin_configs/1","value":{"plugins":{"limit-count":{"rejected_code":503,"time_window":60,"key":"remote_addr","key_type":"var","count":2,"allow_degradation":false,"show_limit_quota_header":true,"policy":"local"},"prometheus":{"prefer_name":false}},"desc":"desc","id":"1","create_time":1684380007,"update_time":1684380472}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"updatePluginConfig"},"delete":{"summary":"Delete a Plugin Config","description":"Delete a plugin config by its ID.","tags":["Plugin Configs"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"name":"force","in":"query","description":"Delete resource by force even if the resource is in use.","required":false,"example":"true","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"Unique key identifier for this plugin configuration in the data store.","type":"string"},"deleted":{"description":"The ID of the successfully deleted plugin configuration.","type":"string"}}},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/plugin_configs/1","deleted":"1"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"deletePluginConfig"}},"/apisix/admin/plugin_metadata":{"get":{"summary":"List All Plugin Metadata","description":"Retrieve metadata for all plugins that have metadata configured.","tags":["Plugin Metadata"],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"list":{"description":"A list of plugin metadata.","type":"array","items":{"type":"object","properties":{"value":{"description":"Plugin metadata values.","type":"object","properties":{}},"key":{"description":"Unique key identifier for this plugin metadata in the data store.","type":"string"},"modifiedIndex":{"description":"The index number representing the most recent update to the object. It starts with the same value as `createdIndex` and increases by 1 each time the resource is modified.","type":"integer"},"createdIndex":{"description":"The index number representing when the object was first created. It indicates the creation order of the resource.","type":"integer"}}}},"total":{"description":"Total number of plugin metadata entries available.","type":"integer"}}},"examples":{"1":{"summary":"Successful Example","value":{"list":[{"value":{"log_format":{"host":"$host","@timestamp":"$time_iso8601","client_ip":"$remote_addr"}},"key":"/apisix/plugin_metadata/syslog","modifiedIndex":283,"createdIndex":283}],"total":1}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listPluginMetadata"}},"/apisix/admin/plugin_metadata/{plugin_name}":{"put":{"summary":"Create or Replace Plugin Metadata","description":"Set metadata for a specific plugin. This applies to all instances of the plugin across the cluster.","tags":["Plugin Metadata"],"parameters":[{"$ref":"#/components/parameters/PluginNameInPath"},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/PluginMetadataUpsert"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"Unique key identifier for this plugin metadata in the data store.","type":"string"},"value":{"description":"Plugin metadata values.","type":"object","properties":{}}}},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/plugin_metadata/syslog","value":{"log_format":{"host":"$host","@timestamp":"$time_iso8601","client_ip":"$remote_addr"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createPluginMetadata"},"get":{"summary":"Get Plugin Metadata","description":"Retrieve metadata for a specific plugin by plugin name.","tags":["Plugin Metadata"],"parameters":[{"$ref":"#/components/parameters/PluginNameInPath"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"value":{"description":"Plugin metadata values.","type":"object","properties":{}},"key":{"description":"Unique key identifier for this plugin metadata in the data store.","type":"string"},"modifiedIndex":{"description":"The index number representing the most recent update to the object. It starts with the same value as `createdIndex` and increases by 1 each time the resource is modified.","type":"integer"},"createdIndex":{"description":"The index number representing when the object was first created. It indicates the creation order of the resource.","type":"integer"}}},"examples":{"1":{"summary":"Successful Example","value":{"value":{"log_format":{"host":"$host","@timestamp":"$time_iso8601","client_ip":"$remote_addr"}},"key":"/apisix/plugin_metadata/syslog","modifiedIndex":156,"createdIndex":156}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"getPluginMetadata"},"delete":{"summary":"Delete Plugin Metadata","description":"Delete metadata for a specific plugin.","tags":["Plugin Metadata"],"parameters":[{"$ref":"#/components/parameters/PluginNameInPath"},{"name":"force","in":"query","description":"Delete resource by force even if the resource is in use.","required":false,"example":"true","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"Unique key identifier for this plugin metadata in the data store.","type":"string"},"deleted":{"description":"The ID of the successfully deleted plugin metadata.","type":"string"}}},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/plugin_metadata/syslog","deleted":"1"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"deletePluginMetadata"}},"/apisix/admin/plugins/list":{"get":{"summary":"List Plugin Names","description":"Get a list of all available plugin names, optionally filtered by subsystem (`http` or `stream`).","tags":["Plugins"],"parameters":[{"$ref":"#/components/parameters/Subsystem"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"array","description":"An array of plugin names.","items":{"type":"string"}},"examples":{"1":{"summary":"Successful Example","value":["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"]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listPluginNames"}},"/apisix/admin/plugins/{plugin_name}":{"get":{"summary":"Get Plugin JSON Schema","description":"Retrieve the JSON Schema definition for a specific plugin. This is useful for validating plugin configurations before applying them.","tags":["Plugins"],"parameters":[{"$ref":"#/components/parameters/PluginNameInPath"},{"$ref":"#/components/parameters/Subsystem"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"if":{"description":"Condition for when a specific policy or configuration is selected.","type":"object","properties":{"properties":{"description":"Properties to validate in the conditional check.","type":"object"}}},"else":{"description":"Alternative condition for other policies or configurations.","type":"object","properties":{"then":{"description":"Schema to apply when the alternative condition is met.","type":"object","properties":{"required":{"description":"Required fields for the configuration when this condition is met.","type":"array","items":{"type":"string"}},"properties":{"description":"Properties for the configuration when this condition is met.","type":"object"}}},"if":{"description":"Condition for when another specific policy or configuration is selected.","type":"object","properties":{"properties":{"description":"Properties to validate in this alternative condition.","type":"object"}}}}},"required":{"type":"array","description":"List of required property names for the plugin configuration.","items":{"type":"string"}},"then":{"description":"Schema to apply when the primary condition is met.","type":"object","properties":{"required":{"description":"Required fields for the configuration when this condition is met.","type":"array","items":{"type":"string"}},"properties":{"description":"Properties for the configuration when this condition is met.","type":"object"}}},"type":{"description":"JSON Schema type definition.","type":"string"},"$comment":{"description":"Comment metadata for the schema.","type":"string"},"properties":{"description":"Properties of the plugin.","type":"object"}}},"examples":{"1":{"summary":"Successful Example","value":{"$comment":"this is a mark for our injected plugin schema.","type":"object","required":["count","time_window"],"properties":{"_meta":{"description":"Metadata configuration for the plugin.","type":"object","additionalProperties":false,"properties":{"disable":{"description":"If set to true, disables the plugin execution.","type":"boolean"},"error_response":{"description":"Custom error response when the plugin rejects a request.","oneOf":[{"type":"string"},{"type":"object"}]},"filter":{"description":"Filter determines whether the plugin needs to be executed at runtime.","type":"array","items":{}},"pre_function":{"description":"Function to be executed before plugin execution with access to conf and ctx parameters.","type":"string"},"priority":{"description":"Priority of plugins by customized order.","type":"integer"}}},"allow_degradation":{"description":"If set to true, enables degradation when the rate limiting backend is unavailable.","type":"boolean","default":false},"count":{"description":"Maximum number of requests allowed within the time window.","type":"integer","exclusiveMinimum":0},"group":{"description":"Group identifier for the rate limiting configuration.","type":"string"},"key":{"description":"Key to use for rate limiting identification.","type":"string","default":"remote_addr"},"key_type":{"description":"Type of the key used for rate limiting.","type":"string","enum":["var","var_combination","constant"],"default":"var"},"policy":{"description":"Policy for rate limiting behavior.","type":"string","enum":["local","redis","redis-cluster"],"default":"local"},"rejected_code":{"description":"HTTP status code returned when requests exceed the limit.","type":"integer","default":503,"minimum":200,"maximum":599},"rejected_msg":{"description":"Custom message returned when requests exceed the limit.","type":"string","minLength":1},"show_limit_quota_header":{"description":"If set to true, adds X-RateLimit-Limit and X-RateLimit-Remaining headers to responses.","type":"boolean","default":true},"time_window":{"description":"Time window in seconds for rate limiting.","type":"integer","exclusiveMinimum":0}},"if":{"properties":{"policy":{"enum":["redis"]}}},"then":{"properties":{"redis_database":{"description":"Redis database index.","type":"integer","default":0,"minimum":0},"redis_host":{"description":"Redis server host address.","type":"string","minLength":2},"redis_password":{"description":"Password for Redis authentication.","type":"string","minLength":0},"redis_port":{"description":"Redis server port.","type":"integer","default":6379,"minimum":1},"redis_ssl":{"description":"If set to true, enables SSL encryption for Redis connections.","type":"boolean","default":false},"redis_ssl_verify":{"description":"If set to true, verifies SSL certificates for Redis connections.","type":"boolean","default":false},"redis_timeout":{"description":"Timeout in milliseconds for Redis operations.","type":"integer","default":1000,"minimum":1},"redis_username":{"description":"Username for Redis authentication.","type":"string","minLength":1}},"required":["redis_host"]},"else":{"if":{"properties":{"policy":{"enum":["redis-cluster"]}}},"then":{"properties":{"redis_cluster_name":{"description":"Name of the Redis cluster.","type":"string"},"redis_cluster_nodes":{"description":"List of Redis cluster node addresses.","type":"array","minItems":1,"items":{"type":"string","minLength":2,"maxLength":100}},"redis_cluster_ssl":{"description":"If set to true, enables SSL encryption for Redis cluster connections.","type":"boolean","default":false},"redis_cluster_ssl_verify":{"description":"If set to true, verifies SSL certificates for Redis cluster connections.","type":"boolean","default":false},"redis_password":{"description":"Password for Redis cluster authentication.","type":"string","minLength":0},"redis_timeout":{"description":"Timeout in milliseconds for Redis cluster operations.","type":"integer","default":1000,"minimum":1}},"required":["redis_cluster_nodes","redis_cluster_name"]}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"getPluginSchema"}},"/apisix/admin/plugins":{"get":{"summary":"List Plugin Attributes","description":"Get attributes of all plugins configured on the APISIX instance.\n\n> **Deprecated:** This endpoint is being replaced. Use `GET /plugins/list` and `GET /plugins/{plugin_name}` instead.","tags":["Plugins"],"parameters":[{"$ref":"#/components/parameters/PluginListAll"},{"$ref":"#/components/parameters/Subsystem"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"plugin_name":{"description":"Plugin configuration and metadata.","type":"object","properties":{"version":{"description":"Plugin schema version number.","type":"number"},"schema":{"description":"JSON Schema defining the plugin configuration structure.","type":"object","properties":{"required":{"description":"Required fields for the plugin.","type":"array","items":{"type":"string"}},"type":{"description":"JSON Schema type definition.","type":"string"},"$comment":{"description":"Comment metadata for the schema.","type":"string"},"properties":{"description":"Plugin properties.","type":"object"}}},"priority":{"description":"Execution priority of the plugin.","type":"integer"}}}}},"examples":{"1":{"summary":"Successful Example","value":{"limit-conn":{"priority":1003,"version":0.1,"schema":{"type":"object","$comment":"this is a mark for our injected plugin schema","required":["conn","burst","default_conn_delay","key"],"properties":{"only_use_default_delay":{"type":"boolean","default":false},"conn":{"type":"integer","exclusiveMinimum":0},"burst":{"type":"integer","minimum":0},"key_type":{"type":"string","enum":["var","var_combination"],"default":"var"},"_meta":{"type":"object","properties":{"filter":{"type":"array","description":"filter determines whether the plugin needs to be executed at runtime","items":{}},"error_response":{"oneOf":[{"type":"string"},{"type":"object"}]},"priority":{"type":"integer","description":"priority of plugins by customized order"},"disable":{"type":"boolean"}}},"key":{"type":"string"},"default_conn_delay":{"type":"number","exclusiveMinimum":0}}}},"syslog":{"schema":{"type":"object","$comment":"this is a mark for our injected plugin schema","required":["host","port"],"properties":{"_meta":{"type":"object","properties":{"filter":{"type":"array","description":"filter determines whether the plugin needs to be executed at runtime","items":{}},"error_response":{"oneOf":[{"type":"string"},{"type":"object"}]},"priority":{"type":"integer","description":"priority of plugins by customized order"},"disable":{"type":"boolean"}}},"host":{"type":"string"},"max_retry_count":{"type":"integer","default":0,"minimum":0},"drop_limit":{"type":"integer","default":1048576},"flush_limit":{"type":"integer","default":4096,"minimum":1},"pool_size":{"type":"integer","default":5,"minimum":5},"sock_type":{"type":"string","default":"tcp","enum":["tcp","udp"]},"buffer_duration":{"type":"integer","default":60,"minimum":1},"retry_delay":{"type":"integer","default":1,"minimum":0},"tls":{"type":"boolean","default":false},"name":{"type":"string","default":"stream sys logger"},"log_format":{"type":"object"},"batch_max_size":{"type":"integer","default":1000,"minimum":1},"timeout":{"type":"integer","default":3000,"minimum":1},"inactive_timeout":{"type":"integer","default":5,"minimum":1},"port":{"type":"integer"}}},"priority":401,"version":0.1,"metadata_schema":{"type":"object","properties":{"log_format":{"type":"object","default":{"@timestamp":"$time_iso8601","host":"$host","client_ip":"$remote_addr"}}}}},"ip-restriction":{"priority":3000,"version":0.1,"schema":{"type":"object","oneOf":[{"required":["whitelist"]},{"required":["blacklist"]}],"$comment":"this is a mark for our injected plugin schema","properties":{"message":{"type":"string","minLength":1,"maxLength":1024,"default":"Your IP address is not allowed"},"_meta":{"type":"object","properties":{"filter":{"type":"array","description":"filter determines whether the plugin needs to be executed at runtime","items":{}},"error_response":{"oneOf":[{"type":"string"},{"type":"object"}]},"priority":{"type":"integer","description":"priority of plugins by customized order"},"disable":{"type":"boolean"}}},"blacklist":{"type":"array","minItems":1,"items":{"anyOf":[{"type":"string","format":"ipv4","title":"IPv4"},{"type":"string","pattern":"^([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])/([12]?[0-9]|3[0-2])$","title":"IPv4/CIDR"},{"type":"string","format":"ipv6","title":"IPv6"},{"type":"string","pattern":"^([a-fA-F0-9]{0,4}:){1,8}(:[a-fA-F0-9]{0,4}){0,8}([a-fA-F0-9]{0,4})?/[0-9]{1,3}$","title":"IPv6/CIDR"}]}},"whitelist":{"type":"array","minItems":1,"items":{"anyOf":[{"type":"string","format":"ipv4","title":"IPv4"},{"type":"string","pattern":"^([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])/([12]?[0-9]|3[0-2])$","title":"IPv4/CIDR"},{"type":"string","format":"ipv6","title":"IPv6"},{"type":"string","pattern":"^([a-fA-F0-9]{0,4}:){1,8}(:[a-fA-F0-9]{0,4}){0,8}([a-fA-F0-9]{0,4})?/[0-9]{1,3}$","title":"IPv6/CIDR"}]}}}}},"mqtt-proxy":{"priority":1000,"version":0.1,"schema":{"type":"object","$comment":"this is a mark for our injected plugin schema","required":["protocol_name","protocol_level"],"properties":{"_meta":{"type":"object","properties":{"filter":{"type":"array","description":"filter determines whether the plugin needs to be executed at runtime","items":{}},"error_response":{"oneOf":[{"type":"string"},{"type":"object"}]},"priority":{"type":"integer","description":"priority of plugins by customized order"},"disable":{"type":"boolean"}}},"protocol_name":{"type":"string"},"protocol_level":{"type":"integer"}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Not found plugin name"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listPluginAttributes"}},"/apisix/admin/plugins/reload":{"put":{"summary":"Hot-Reload Plugins","description":"Trigger a hot reload of all plugins. This re-reads plugin configurations from etcd without restarting APISIX.\n\n**Important:** Only the `PUT` method is accepted.","tags":["Plugins"],"parameters":[],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"string"},"examples":{"1":{"summary":"Successful Example","value":"done"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"reloadPlugins","x-codeSamples":[{"lang":"cURL","label":"cURL","source":"curl -i http://127.0.0.1:9180/apisix/admin/plugins/reload \\\n  -H 'X-API-KEY: your-api-key' -X PUT"}]}},"/apisix/admin/stream_routes":{"get":{"summary":"List All Stream Routes","description":"Retrieve all configured stream (L4) routes.\n\n**Prerequisite:** Stream mode must be enabled in `config.yaml`.","tags":["Stream Routes"],"parameters":[{"$ref":"#/components/parameters/NameFilter"},{"$ref":"#/components/parameters/LabelFilter"},{"$ref":"#/components/parameters/FilterExpr"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StreamRouteListEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"total":1,"list":[{"createdIndex":173,"key":"/apisix/stream_routes/1","value":{"id":"1","create_time":1684392990,"server_addr":"127.0.0.1","upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"127.0.0.1:1995":1},"type":"roundrobin","scheme":"http"},"update_time":1684392990,"server_port":2000},"modifiedIndex":173}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listStreamRoutes"},"post":{"summary":"Create a Stream Route","description":"Create a new stream route with an auto-generated ID.","tags":["Stream Routes"],"parameters":[{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/StreamRouteUpsertPostCollection"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StreamRouteEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"value":{"id":"00000000000000000176","create_time":1684393167,"server_addr":"127.0.0.1","upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"127.0.0.1:1995":1},"type":"roundrobin","scheme":"http"},"update_time":1684393167,"server_port":2000},"key":"/apisix/stream_routes/00000000000000000176"}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createStreamRoute"}},"/apisix/admin/secrets":{"get":{"summary":"List All Secrets","description":"Retrieve all configured secret manager integrations.","tags":["Secrets"],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"list":{"type":"array","description":"An array of secret configuration objects.","items":{"type":"object","properties":{"value":{"type":"object","description":"Secret values.","properties":{"id":{"type":"string","description":"Unique identifier for the secret configuration, including the secret manager type and ID."},"prefix":{"type":"string","description":"Path prefix of the secret engine that Vault should route to."},"token":{"type":"string","description":"Token used for APISIX to authenticate to Vault."},"create_time":{"type":"integer","description":"Creation time of the secret."},"update_time":{"type":"integer","description":"Update time of the secret."},"uri":{"type":"string","description":"Address of the Vault server."}}},"key":{"description":"Unique key identifier for this secret in the data store.","type":"string"},"modifiedIndex":{"description":"The index number representing the most recent update to the object. It starts with the same value as `createdIndex` and increases by 1 each time the resource is modified.","type":"integer"},"createdIndex":{"description":"The index number representing when the object was first created. It indicates the creation order of the resource.","type":"integer"}}}},"total":{"description":"Total number of secrets matching the query criteria.","type":"integer"}}},"examples":{"1":{"summary":"Successful Example","value":{"total":1,"list":[{"createdIndex":179,"key":"/apisix/secrets/vault/1","value":{"token":"343effad","id":"vault/1","uri":"https://localhost/vault","prefix":"/apisix/kv","update_time":1684395392,"create_time":1684395392},"modifiedIndex":179}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listSecrets"}},"/apisix/admin/protos/{id}":{"put":{"summary":"Create or Replace a Proto","description":"Upload a protobuf definition with a specified ID, or replace an existing one.","tags":["Protos"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"schema":{"type":"string"},"example":"my-resource-1"},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/ProtoUpsertPutId"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtoEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/protos/1","value":{"id":"1","create_time":1684752213,"update_time":1684752213,"content":"syntax = \"proto3\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createProtoById"},"get":{"summary":"Get a Proto","description":"Retrieve a single protobuf definition by its ID.","tags":["Protos"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"schema":{"type":"string"},"example":"my-resource-1"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtoEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"value":{"id":"1","content":"syntax = \"proto3\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }","update_time":1684752213,"create_time":1684752213},"key":"/apisix/protos/1","modifiedIndex":292,"createdIndex":292}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"getProto"},"delete":{"summary":"Delete a Proto","description":"Delete a protobuf definition by its ID.","tags":["Protos"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"schema":{"type":"string"},"example":"my-resource-1"},{"name":"force","in":"query","description":"Delete resource by force even if the resource is in use.","required":false,"example":"true","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"Unique key identifier for this proto in the data store."},"deleted":{"type":"string","description":"The ID of the successfully deleted proto."}}},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/protos/1","deleted":"1"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"deleteProto"}},"/apisix/admin/protos":{"get":{"summary":"List All Protos","description":"Retrieve all stored protobuf definitions.","tags":["Protos"],"parameters":[{"$ref":"#/components/parameters/NameFilter"},{"$ref":"#/components/parameters/LabelFilter"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtoListEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"list":[{"value":{"id":"1","content":"syntax = \"proto3\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }","update_time":1684752213,"create_time":1684752213},"key":"/apisix/protos/1","modifiedIndex":292,"createdIndex":292}],"total":1}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listProtos"},"post":{"summary":"Create a Proto","description":"Upload a new protobuf definition with an auto-generated ID.","tags":["Protos"],"parameters":[{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/ProtoUpsertPostCollection"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtoEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/protos/00000000000000000293","value":{"create_time":1684752743,"update_time":1684752743,"content":"syntax = \"proto3\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }","id":"00000000000000000293"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createProto"}},"/apisix/admin/schema/validate/{resource}":{"post":{"summary":"Validate Resource Configuration","description":"Validate a resource configuration against APISIX's JSON Schema without creating the resource. Useful for dry-run validation in CI/CD pipelines.\n\nThe `{resource}` path parameter specifies the resource type (e.g., `routes`, `upstreams`, `services`, etc.).","tags":["Schema Validation"],"parameters":[{"$ref":"#/components/parameters/ResourceKindInPath"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"The resource configuration to validate. The structure depends on the resource type specified in the path parameter.","additionalProperties":true},"example":{"uri":"/api/v1/*","upstream":{"scheme":"https","type":"roundrobin","nodes":{"httpbin.org:443":1}}}}}},"responses":{"200":{"description":"Successful response.","content":{}},"400":{"$ref":"#/components/responses/BadRequest","description":"Bad Request"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"validateResourceSchema"}},"/apisix/admin/stream_routes/{id}":{"get":{"summary":"Get Stream Route by ID","description":"Get stream route by ID.","tags":["Stream Routes"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"schema":{"type":"string"},"example":"my-resource-1"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","description":"Response object containing the list of stream routes.","properties":{"items":{"type":"object","description":"Stream route entry with metadata.","properties":{"value":{"description":"Stream route values.","properties":{"desc":{"maxLength":256,"type":"string","description":"Description of the stream route."},"upstream_id":{"description":"Upstream ID.","anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$"},{"minimum":1,"type":"integer"}]},"update_time":{"type":"integer","description":"Update time of the stream route."},"create_time":{"type":"integer","description":"Creation time of the stream route."},"sni":{"type":"string","description":"SNI hostname to match. Supports wildcard hostnames. Mutually exclusive with `snis`.","pattern":"^\\*$|^\\*?[0-9a-zA-Z-._\\[\\]:]+$"},"id":{"description":"Unique identifier for the stream route.","anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$"},{"minimum":1,"type":"integer"}]},"remote_addr":{"description":"Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.","type":"string","anyOf":[{"format":"ipv4","type":"string","title":"IPv4"},{"type":"string","title":"IPv4/CIDR","pattern":"^([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])/([12]?[0-9]|3[0-2])$"},{"format":"ipv6","type":"string","title":"IPv6"},{"type":"string","title":"IPv6/CIDR","pattern":"^([a-fA-F0-9]{0,4}:){1,8}(:[a-fA-F0-9]{0,4}){0,8}([a-fA-F0-9]{0,4})?/[0-9]{1,3}$"}]},"protocol":{"description":"Protocol configuration for the stream route.","properties":{"logger":{"description":"An array of logger plugin configurations.","items":{"description":"Logger configuration item.","properties":{"conf":{"type":"object","description":"Logger plugin configuration.","properties":{}},"filter":{"type":"array","description":"Logger filter rules.","items":{"type":"string","description":"A filter rule pattern."}},"name":{"type":"string","description":"Name of the logger plugin."}},"type":"object","dependentRequired":{"name":["conf"]}},"type":"array"},"conf":{"type":"object","description":"Protocol-specific configuration.","properties":{}},"superior_id":{"description":"ID of a superior protocol configuration.","anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$"},{"minimum":1,"type":"integer"}]},"name":{"type":"string","description":"Name of the protocol."}},"type":"object","required":["name"]},"server_addr":{"type":"string","description":"Server IP address.","anyOf":[{"format":"ipv4","type":"string","title":"IPv4"},{"type":"string","title":"IPv4/CIDR","pattern":"^([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])/([12]?[0-9]|3[0-2])$"},{"format":"ipv6","type":"string","title":"IPv6"},{"type":"string","title":"IPv6/CIDR","pattern":"^([a-fA-F0-9]{0,4}:){1,8}(:[a-fA-F0-9]{0,4}){0,8}([a-fA-F0-9]{0,4})?/[0-9]{1,3}$"}]},"upstream":{"description":"Upstream configuration for the stream route.","properties":{"desc":{"maxLength":256,"type":"string","description":"Description of the upstream."},"update_time":{"type":"integer","description":"Update time of the stream route."},"key":{"type":"string","description":"The key used with `hash_on` when `type` is `chash`.<br>When `hash_on` is set to `header` or `cookie`, `key` is required.<br>When `hash_on` is set to `vars` or `vars_combinations`, `key` is required and supports [built-in variables](/apisix/reference/built-in-variables).<br>When `hash_on` is set to `consumer`, `key` is not required as the consumer name will be used as the key automatically."},"retries":{"minimum":0,"type":"integer","description":"The number of retries while passing the request to an upstream."},"retry_timeout":{"minimum":0,"type":"number","description":"Timeout to continue with retries. Setting this to 0 disables the retry timeout."},"pass_host":{"default":"pass","type":"string","enum":["pass","node","rewrite"],"description":"How to set the `Host` header when proxying to the upstream.","x-enumDescriptions":{"pass":"Forward the client's original `Host` header.","node":"Use the upstream node's hostname.","rewrite":"Use the value of `upstream_host`."}},"upstream_host":{"type":"string","description":"Configure the host when the request is forwarded to the upstream. `pass` is used to pass the request's host to the upstream without modification. `node` sets the host to the host of the upstream node. `rewrite` sets the host to the value of `upstream_host`."},"type":{"type":"string","default":"roundrobin","enum":["roundrobin","chash","ewma","least_conn"],"description":"Load balancing algorithm. Support weighted round robin, consistent hashing, exponentially weighted moving average, and least connections algorithms."},"checks":{"description":"Health check configurations.","properties":{"active":{"description":"Active health check configuration.","properties":{"port":{"type":"integer","description":"By default, the port is the same as the one defined in the upstream target.","minimum":1,"maximum":65535},"healthy":{"description":"Active health check healthy configurations.","properties":{"http_statuses":{"description":"A list of HTTP response status codes which are considered healthy.","uniqueItems":true,"items":{"type":"integer","minimum":200,"maximum":599},"type":"array","minItems":1,"default":[200,302]},"interval":{"description":"Time interval of checking healthy targets in seconds.","type":"integer","minimum":1,"default":1},"successes":{"description":"The number of successful probes to define a healthy target.","default":2,"type":"integer","minimum":1,"maximum":254}},"type":"object"},"http_path":{"description":"The HTTP path in HTTP probe requests.","default":"/","type":"string"},"https_verify_certificate":{"description":"If true, verify the target's TLS certificate.","default":true,"type":"boolean"},"unhealthy":{"description":"Active health check unhealthy configurations.","properties":{"interval":{"description":"Time interval of checking unhealthy targets in seconds.","type":"integer","minimum":1,"default":1},"tcp_failures":{"description":"The number of TCP-related failures to define an unhealthy target.","default":2,"type":"integer","minimum":1,"maximum":254},"timeouts":{"description":"The number of probe timeouts to define an unhealthy target.","default":3,"type":"integer","minimum":1,"maximum":254},"http_statuses":{"description":"A list of HTTP response status codes which are considered unhealthy.","uniqueItems":true,"items":{"type":"integer","minimum":200,"maximum":599},"type":"array","minItems":1,"default":[429,404,500,501,502,503,504,505]},"http_failures":{"description":"The number of HTTP-related failures to define an unhealthy target.","default":5,"type":"integer","minimum":1,"maximum":254}},"type":"object"},"req_headers":{"description":"The request headers.","items":{"type":"string"},"type":"array","minItems":1},"timeout":{"description":"Active check timeout in seconds.","default":1,"type":"number"},"type":{"description":"Active check probing type.","enum":["http","https","tcp"],"default":"http","type":"string"},"host":{"type":"string","description":"Host header value for health check probes sent to upstream nodes."},"concurrency":{"default":10,"type":"integer","description":"The number of targets to be checked at the same time during the active check."}},"type":"object"},"passive":{"description":"Passive health check configurations.","properties":{"healthy":{"description":"Passive health check healthy configurations.","properties":{"http_statuses":{"description":"A list of HTTP response status codes which are considered healthy.","uniqueItems":true,"items":{"type":"integer","minimum":200,"maximum":599},"type":"array","minItems":1,"default":[200,201,202,203,204,205,206,207,208,226,300,301,302,303,304,305,306,307,308]},"successes":{"description":"The number of successful probes to define a healthy target.","default":5,"type":"integer","minimum":0,"maximum":254}},"type":"object"},"unhealthy":{"description":"Passive health check unhealthy configurations.","properties":{"http_statuses":{"description":"A list of HTTP response status codes which are considered unhealthy.","uniqueItems":true,"items":{"type":"integer","minimum":200,"maximum":599},"type":"array","minItems":1,"default":[429,500,503]},"http_failures":{"description":"The number of HTTP-related failures to define an unhealthy target.","default":5,"type":"integer","minimum":0,"maximum":254},"tcp_failures":{"description":"The number of TCP-related failures to define an unhealthy target.","default":2,"type":"integer","minimum":0,"maximum":254},"timeouts":{"description":"The number of probe timeouts to define an unhealthy target.","default":7,"type":"integer","minimum":0,"maximum":254}},"type":"object"},"type":{"description":"Passive check probing type.","enum":["http","https","tcp"],"default":"http","type":"string"}},"type":"object"}},"type":"object","anyOf":[{"title":"Active Check","required":["active"]},{"title":"Passive Check","required":["active","passive"]}]},"hash_on":{"default":"vars","enum":["vars","header","cookie","consumer","vars_combinations"],"description":"What to hash on when `type` is `chash`.","type":"string","x-enumDescriptions":{"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."}},"name":{"description":"Upstream name.","type":"string","maxLength":100,"minLength":1},"scheme":{"enum":["grpc","grpcs","http","https","ws","wss","tcp","tls","udp","kafka"],"default":"http","description":"Protocol for communicating with upstream nodes.","x-enumDescriptions":{"grpc":"Layer 7 gRPC.","grpcs":"Layer 7 gRPC over TLS.","http":"Layer 7 HTTP.","https":"Layer 7 HTTP over TLS.","tcp":"Layer 4 TCP.","tls":"Layer 4 TCP over TLS.","udp":"Layer 4 UDP.","kafka":"Apache Kafka protocol.","ws":"Frame-aware WebSocket proxying; `enable_websocket` is ignored.","wss":"Frame-aware WebSocket proxying over TLS; uses the shared CA trust store, not `tls.ca_certs`."}},"keepalive_pool":{"description":"Upstream keepalive connection pool.","properties":{"size":{"description":"The number of idle keepalive connections per worker to upstream servers.","default":320,"minimum":1,"type":"integer"},"idle_timeout":{"description":"Time an idle keepalive connection remains open before being closed, in seconds.","default":60,"minimum":0,"type":"number"},"requests":{"description":"The number of requests a single keepalive connection can handle before closing.","default":1000,"minimum":1,"type":"integer"}},"type":"object"},"timeout":{"description":"Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.","properties":{"connect":{"description":"Connection timeout in seconds.","exclusiveMinimum":0,"type":"number"},"read":{"description":"Receiving timeout in seconds.","exclusiveMinimum":0,"type":"number"},"send":{"description":"Sending timeout in seconds.","exclusiveMinimum":0,"type":"number"}},"type":"object"},"id":{"description":"Upstream ID.","anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$"},{"minimum":1,"type":"integer"}]},"labels":{"type":"object","patternProperties":{".*":{"minLength":1,"maxLength":64,"pattern":"^\\S+$","type":"string","description":"Value of label."}},"description":"Key-value pairs to specify attributes.","properties":{}},"discovery_args":{"description":"Service discovery arguments.","properties":{"group_name":{"type":"string","description":"Group name."},"namespace_id":{"type":"string","description":"Namespace ID."}},"type":"object"},"tls":{"description":"TLS configurations.","properties":{"verify":{"type":"boolean","description":"Whether to verify the upstream server certificate. If omitted for HTTPS/gRPCS, follows the NGINX verification setting, which is off unless enabled. Explicit `false` disables verification. For `wss`, explicitly set `true` to enable verification against the shared trust store."},"client_key":{"description":"Private key.","minLength":64,"maxLength":65536,"type":"string"},"client_cert":{"description":"Client certificate.","minLength":128,"maxLength":65536,"type":"string"},"client_cert_id":{"description":"Client certificate ID.","anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$"},{"minimum":1,"type":"integer"}]},"ca_certs":{"type":"array","minItems":1,"items":{"type":"string","minLength":128,"maxLength":65536},"description":"PEM-encoded CA certificates for HTTPS/gRPCS upstream verification. Replaces the NGINX trust store for this upstream. If omitted, configure and load the shared store using `proxy_ssl_verify` for HTTPS or `grpc_ssl_verify` for gRPCS. See [Configure Upstream HTTPS](/apisix/how-to-guide/traffic-management/tls-and-mtls/configure-upstream-https). Does not enable verification by itself; set `tls.verify` to `true`. Rejected for `ws` and `wss` upstreams."}},"type":"object","dependentSchemas":{"client_cert_id":{"not":{"required":["client_cert","client_key"]}},"client_cert":{"required":["client_key"],"not":{"required":["client_cert_id"]}},"client_key":{"required":["client_cert"],"not":{"required":["client_cert_id"]}}}},"create_time":{"description":"Creation time of the upstream.","type":"integer"},"warm_up_conf":{"$ref":"#/components/schemas/UpstreamWarmUp"}},"additionalProperties":false,"type":"object","oneOf":[{"title":"Use Upstream Nodes","required":["nodes"],"properties":{"nodes":{"description":"The upstream endpoints.","anyOf":[{"title":"Weight Mapping","patternProperties":{".*":{"type":"integer","minimum":0,"description":"Weight of a node. For example, in `{\"ip:port\": 100}`, the value `100` represents the node's weight."}},"type":"object"},{"title":"Node Objects","items":{"properties":{"weight":{"type":"integer","minimum":0,"description":"Weight of a node."},"port":{"type":"integer","minimum":1,"description":"Port of a node."},"metadata":{"type":"object","description":"Metadata of a node."},"host":{"description":"Upstream host.","type":"string"},"priority":{"type":"integer","default":0,"description":"Priority of a node. A higher value corresponds to a higher priority."}},"type":"object"},"type":"array"}]}}},{"title":"Use Service Registry","required":["service_name","discovery_type"],"properties":{"service_name":{"description":"Service name in the service registry. Only valid for service discovery.","type":"string","maxLength":256,"minLength":1},"discovery_type":{"type":"string","description":"Discovery type."}}}]},"plugins":{"description":"Key-value pairs of plugins and their configurations on the object.","type":"object","properties":{}},"server_port":{"type":"integer","description":"Server port."},"snis":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","pattern":"^\\*$|^\\*?[0-9a-zA-Z-._\\[\\]:]+$"},"description":"Alternative SNI hostnames to match, including wildcard hostnames. Mutually exclusive with `sni`."},"tls_passthrough":{"type":"boolean","default":false,"description":"On a listener configured with both `tls` and `tls_passthrough`, `true` forwards encrypted TLS bytes to the upstream; `false` terminates TLS at APISIX. Ignored on dedicated listeners. Passthrough requires a TCP upstream, not scheme `tls`."}},"type":"object","not":{"required":["sni","snis"]}},"key":{"description":"Unique key identifier for this stream route in the data store.","type":"string"},"modifiedIndex":{"description":"The index number representing the most recent update to the object. It starts with the same value as `createdIndex` and increases by 1 each time the resource is modified.","type":"integer"},"createdIndex":{"description":"The index number representing when the object was first created. It indicates the creation order of the resource.","type":"integer"}}}}},"examples":{"1":{"summary":"Successful Example","value":{"id":"1","create_time":1684392990,"server_addr":"127.0.0.1","upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"127.0.0.1:1995":1},"type":"roundrobin","scheme":"http"},"update_time":1684392990,"server_port":2000}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"getId]"},"put":{"summary":"Create Stream Route by ID","description":"Create a stream route with a specified ID.","tags":["Stream Routes"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/StreamRouteUpsertPutId"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StreamRouteEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"value":{"id":"00000000000000000176","create_time":1684393167,"server_addr":"127.0.0.1","upstream":{"hash_on":"vars","pass_host":"pass","nodes":{"127.0.0.1:1995":1},"type":"roundrobin","scheme":"http"},"update_time":1684393167,"server_port":2000},"key":"/apisix/stream_routes/00000000000000000176"}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"putId]"},"delete":{"summary":"Delete Stream Route by ID","description":"Delete a stream route by ID.","tags":["Stream Routes"],"parameters":[{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"name":"force","in":"query","description":"Delete resource by force even if the resource is in use.","required":false,"example":"true","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"Unique key identifier for this stream route in the data store.","type":"string"},"deleted":{"description":"The ID of the successfully deleted stream route.","type":"string"}}},"examples":{"1":{"summary":"Successful Example","value":{"deleted":"1","key":"/apisix/stream_routes/1"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"deleteId]"}},"/apisix/admin/consumers/{username}/credentials":{"get":{"summary":"List Consumer Credentials","description":"Retrieve all credentials for a specific consumer.","tags":["Credentials"],"parameters":[{"$ref":"#/components/parameters/UsernameInPath"},{"$ref":"#/components/parameters/NameFilter"},{"$ref":"#/components/parameters/LabelFilter"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialListEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"total":2,"list":[{"key":"/apisix/consumers/john/credentials/cred-john-basic-auth","value":{"update_time":1725991703,"id":"cred-john-basic-auth","plugins":{"basic-auth":{"password":"john-pass","username":"john-key"}},"create_time":1725991529},"createdIndex":42,"modifiedIndex":44},{"key":"/apisix/consumers/john/credentials/cred-john-key-auth","value":{"update_time":1725991703,"id":"cred-john-key-auth","plugins":{"key-auth":{"key":"john-key"}},"create_time":1725991703},"createdIndex":43,"modifiedIndex":43}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"listCredentials"}},"/apisix/admin/consumers/{username}/credentials/{id}":{"get":{"summary":"Get a Credential","description":"Retrieve a specific credential for a consumer.","tags":["Credentials"],"parameters":[{"$ref":"#/components/parameters/UsernameInPath"},{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialListEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"total":1,"list":[{"key":"/apisix/consumers/john/credentials/cred-john-basic-auth","value":{"update_time":1725991529,"id":"cred-john-basic-auth","plugins":{"basic-auth":{"password":"john-pass","username":"john-key"}},"create_time":1725991529},"createdIndex":42,"modifiedIndex":42}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"getCredential"},"put":{"summary":"Create or Replace a Credential","description":"Create a new credential for a consumer with a specified ID, or replace an existing one.\n\nEach credential holds exactly one authentication plugin.","tags":["Credentials"],"parameters":[{"$ref":"#/components/parameters/UsernameInPath"},{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/CredentialUpsert"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialEnvelope"},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/consumers/john/credentials/cred-john-key-auth","value":{"create_time":1725991703,"id":"cred-john-key-auth","plugins":{"key-auth":{"key":"john-key"}},"update_time":1725991703}}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createCredentialById"},"delete":{"summary":"Delete a Credential","description":"Delete a specific credential from a consumer.","tags":["Credentials"],"parameters":[{"$ref":"#/components/parameters/UsernameInPath"},{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Force"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"The storage key or path identifier for the consumer credential.","type":"string"},"deleted":{"description":"The ID of the successfully deleted consumer credential.","type":"string"}}},"examples":{"1":{"summary":"Successful Example","value":{"key":"/apisix/consumers/john/credentials/cred-john-key-auth","deleted":"1"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"deleteCredential"}},"/apisix/admin/secrets/{secret_type}/{id}":{"get":{"summary":"Get a Secret","description":"Retrieve a specific secret manager configuration.","tags":["Secrets"],"parameters":[{"name":"secret_type","in":"path","description":"Type of secret manager (e.g., `vault`, `aws`).","required":true,"example":"vault","schema":{"type":"string","enum":["vault","aws","gcp"]}},{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"object","description":"Secret values.","properties":{"id":{"type":"string","description":"Unique identifier for the secret configuration, including the secret manager type and ID."},"prefix":{"type":"string","description":"Path prefix for the secret engine or storage location."},"token":{"type":"string","description":"Authentication token or credential for accessing the secret manager."},"create_time":{"type":"integer","description":"Creation time of the secret."},"update_time":{"type":"integer","description":"Update time of the secret."},"uri":{"type":"string","description":"Endpoint URI of the secret manager service."}}},"key":{"description":"Unique key identifier for this secret in the data store.","type":"string"},"modifiedIndex":{"description":"The index number representing the most recent update to the object. It starts with the same value as `createdIndex` and increases by 1 each time the resource is modified.","type":"integer"},"createdIndex":{"description":"The index number representing when the object was first created. It indicates the creation order of the resource.","type":"integer"}}},"examples":{"1":{"summary":"Successful Example","value":{"createdIndex":179,"key":"/apisix/secrets/vault/1","value":{"token":"343effad","id":"vault/1","uri":"https://localhost/vault","prefix":"/apisix/kv","update_time":1684395392,"create_time":1684395392},"modifiedIndex":179}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"getSecret"},"put":{"summary":"Create or Replace a Secret","description":"Configure a secret manager integration with a specified ID.","tags":["Secrets"],"parameters":[{"name":"secret_type","in":"path","description":"Type of secret manager (e.g., `vault`, `aws`).","required":true,"example":"vault","schema":{"type":"string","enum":["vault","aws","gcp"]}},{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/SecretUpsertPutCollection"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"Unique key identifier for this secret in the data store."},"value":{"type":"object","description":"Secret values.","properties":{"id":{"type":"string","description":"Unique identifier for the secret configuration, including the secret manager type and ID."},"prefix":{"type":"string","description":"Path prefix for the secret engine or storage location."},"token":{"type":"string","description":"Authentication token or credential for accessing the secret manager."},"namespace":{"type":"string","description":"Used to set the [namespace](https://developer.hashicorp.com/vault/docs/enterprise/namespaces#vault-api-and-namespaces) of HashiCorp Vault Enterprise and HCP Vault."},"create_time":{"type":"integer","description":"Creation time of the secret."},"update_time":{"type":"integer","description":"Update time of the secret."},"uri":{"type":"string","description":"Endpoint URI of the secret manager service."}}}}},"examples":{"1":{"summary":"Successful Example","value":{"value":{"prefix":"/apisix/kv","token":"343effad","uri":"https://localhost/vault","namespace":"apisix","id":"vault/1","update_time":1684395392,"create_time":1684395392},"key":"/apisix/secrets/vault/1"}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"createSecretById"},"patch":{"summary":"Update a Secret (Partial)","description":"Partially update a secret manager configuration.","tags":["Secrets"],"parameters":[{"name":"secret_type","in":"path","description":"Type of secret manager (e.g., `vault`, `aws`).","required":true,"example":"vault","schema":{"type":"string","enum":["vault","aws","gcp"]}},{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"$ref":"#/components/requestBodies/SecretUpsertPatchCollection"},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"Unique key identifier for this secret in the data store."},"value":{"type":"object","description":"Secret values.","properties":{"id":{"type":"string","description":"Unique identifier for the secret configuration, including the secret manager type and ID."},"prefix":{"type":"string","description":"Path prefix for the secret engine or storage location."},"token":{"type":"string","description":"Authentication token or credential for accessing the secret manager."},"create_time":{"type":"integer","description":"Creation time of the secret."},"update_time":{"type":"integer","description":"Update time of the secret."},"uri":{"type":"string","description":"Endpoint URI of the secret manager service."}}}}},"examples":{"1":{"summary":"Successful Example","value":{"value":{"token":"apisix","id":"vault/1","uri":"https://localhost/vault","prefix":"/apisix/kv","update_time":1684396605,"create_time":1684395392},"key":"/apisix/secrets/vault/1"}}}}}},"400":{"$ref":"#/components/responses/BadRequest","description":"Invalid configuration"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"updateSecret"},"delete":{"summary":"Delete a Secret","description":"Delete a secret manager configuration.","tags":["Secrets"],"parameters":[{"name":"secret_type","in":"path","description":"Type of secret manager (e.g., `vault`, `aws`).","required":true,"example":"vault","schema":{"type":"string","enum":["vault","aws","gcp"]}},{"name":"id","in":"path","description":"Unique identifier of the resource. Can be a string (alphanumeric, `-`, `_`, `.`) or a positive integer.","required":true,"example":"my-resource-1","schema":{"type":"string"}},{"name":"force","in":"query","description":"Delete resource by force even if the resource is in use.","required":false,"example":"true","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"Unique key identifier for this secret in the data store."},"deleted":{"type":"string","description":"The ID of the successfully deleted secret."}}},"examples":{"1":{"summary":"Successful Example","value":{"deleted":"1","key":"/apisix/secrets/vault/1"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound","description":"Key not found"}},"operationId":"deleteSecret"}},"/apisix/admin":{"head":{"tags":["Health"],"operationId":"ping","summary":"Liveness probe","description":"Returns `200 OK` if the Admin API is reachable. Useful as a Kubernetes liveness probe target. This endpoint does not require authentication.","security":[],"responses":{"200":{"description":"APISIX Admin API is alive."}},"parameters":[]}},"/apisix/admin/configs":{"get":{"tags":["Standalone"],"operationId":"getStandaloneConfig","summary":"Get the standalone configuration","description":"Available in API-driven standalone mode, with the YAML configuration provider and Admin API enabled. Returns the accepted configuration snapshot and its version and digest metadata, not a worker synchronization report. See [API-Driven Standalone Mode Usage](/apisix/reference/api-standalone-usage).","responses":{"200":{"description":"Current standalone configuration.","content":{"application/json":{"schema":{"type":"object"}},"application/yaml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"parameters":[]},"put":{"tags":["Standalone"],"operationId":"putStandaloneConfig","summary":"Replace the standalone configuration","description":"Replace the complete configuration snapshot in API-driven standalone mode. Omitted resources are removed unless their resource type's configuration version is explicitly retained. Validate the complete document before applying it. A client-supplied `X-Digest` is required and must change when the intended configuration changes. APISIX compares the supplied identifier, not a computed hash. A matching digest skips the update and any wait. APISIX supports an optional bounded `wait` for local worker synchronization; this does not verify other instances or upstream health. See [API-Driven Standalone Mode Usage](/apisix/reference/api-standalone-usage).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}},"application/yaml":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"With a positive wait, all local workers reported the submitted digest for their tracked HTTP and enabled stream resource types."},"202":{"description":"Snapshot accepted. No wait was requested, or the wait expired before local worker synchronization was confirmed. A timeout does not roll back the snapshot."},"204":{"description":"The supplied digest matches the stored snapshot. No update or wait was performed; this is not a readiness confirmation."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"parameters":[{"name":"X-Digest","in":"header","required":true,"description":"Client-chosen identifier for this snapshot. Use a new value for changed content.","schema":{"type":"string"}},{"name":"wait","in":"query","description":"Wait timeout in milliseconds. Values above 60000 are capped; absent, nonnumeric, or nonpositive values do not wait.","schema":{"type":"number","default":0},"example":5000}]},"head":{"tags":["Standalone"],"operationId":"headStandaloneConfig","summary":"Probe standalone configuration availability","description":"Returns `200 OK` when the API-driven standalone configuration endpoint is reachable, including before any snapshot is loaded. When available, digest and last-modified metadata are returned in headers. This endpoint does not confirm worker synchronization.","responses":{"200":{"description":"Standalone configuration is reachable."},"401":{"$ref":"#/components/responses/Unauthorized"}},"parameters":[]}},"/apisix/admin/configs/validate":{"post":{"tags":["Schema Validation"],"operationId":"validateConfiguration","summary":"Validate a Configuration Without Applying It","description":"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.\n\nValidation 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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigValidationDocument"}},"application/yaml":{"schema":{"$ref":"#/components/schemas/ConfigValidationDocument"}}}},"responses":{"200":{"description":"The supplied configuration passed all applicable checks.","content":{"application/json":{"schema":{"type":"object","maxProperties":0},"example":{}}}},"400":{"description":"The request body could not be parsed, exceeded 1.5 MiB, or failed one or more configuration checks.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ConfigValidationErrorResponse"}]},"examples":{"invalidBody":{"summary":"Malformed or empty request body","value":{"error_msg":"invalid request body: empty request body"}},"configurationErrors":{"summary":"Multiple configuration errors","value":{"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"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"parameters":[]}},"/apisix/admin/routes/{id}/{sub_path}":{"parameters":[{"$ref":"#/components/parameters/IdInPath"},{"name":"sub_path","in":"path","required":true,"schema":{"type":"string"},"description":"Slash-separated nested key path within the resource document.","example":"status"}],"patch":{"tags":["Routes"],"operationId":"patchRoutesSubPath","summary":"Replace a single nested field of a route","description":"Replaces the value at `sub_path` within the route document with the request body. The body is any valid JSON value, not necessarily an object. The updated complete resource must pass validation.","parameters":[{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{},"example":1}}},"responses":{"200":{"description":"Sub-field replaced."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/apisix/admin/services/{id}/{sub_path}":{"parameters":[{"$ref":"#/components/parameters/IdInPath"},{"name":"sub_path","in":"path","required":true,"schema":{"type":"string"},"description":"Slash-separated nested key path within the resource document.","example":"enable_websocket"}],"patch":{"tags":["Services"],"operationId":"patchServicesSubPath","summary":"Replace a single nested field of a service","description":"Replaces the value at `sub_path` within the service document with the request body. The body is any valid JSON value, not necessarily an object. The updated complete resource must pass validation.","parameters":[{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{},"example":true}}},"responses":{"200":{"description":"Sub-field replaced."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/apisix/admin/upstreams/{id}/{sub_path}":{"parameters":[{"$ref":"#/components/parameters/IdInPath"},{"name":"sub_path","in":"path","required":true,"schema":{"type":"string"},"description":"Slash-separated nested key path within the resource document.","example":"retries"}],"patch":{"tags":["Upstreams"],"operationId":"patchUpstreamsSubPath","summary":"Replace a single nested field of an upstream","description":"Replaces the value at `sub_path` within the upstream document with the request body. The body is any valid JSON value, not necessarily an object. The updated complete resource must pass validation.","parameters":[{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{},"example":3}}},"responses":{"200":{"description":"Sub-field replaced."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/apisix/admin/ssls/{id}/{sub_path}":{"parameters":[{"$ref":"#/components/parameters/IdInPath"},{"name":"sub_path","in":"path","required":true,"schema":{"type":"string"},"description":"Slash-separated nested key path within the resource document.","example":"status"}],"patch":{"tags":["SSL Certificates"],"operationId":"patchSSLCertificatesSubPath","summary":"Replace a single nested field of an SSL certificate","description":"Replaces the value at `sub_path` within the SSL certificate document with the request body. The body is any valid JSON value, not necessarily an object. The updated complete resource must pass validation.","parameters":[{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{},"example":1}}},"responses":{"200":{"description":"Sub-field replaced."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/apisix/admin/consumer_groups/{id}/{sub_path}":{"parameters":[{"$ref":"#/components/parameters/IdInPath"},{"name":"sub_path","in":"path","required":true,"schema":{"type":"string"},"description":"Slash-separated nested key path within the resource document.","example":"plugins"}],"patch":{"tags":["Consumer Groups"],"operationId":"patchConsumerGroupsSubPath","summary":"Replace a single nested field of a consumer group","description":"Replaces the value at `sub_path` within the consumer group document with the request body. The body is any valid JSON value, not necessarily an object. The updated complete resource must pass validation.","parameters":[{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{},"example":{"limit-count":{"count":100,"time_window":60,"rejected_code":429}}}}},"responses":{"200":{"description":"Sub-field replaced."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/apisix/admin/global_rules/{id}/{sub_path}":{"parameters":[{"$ref":"#/components/parameters/IdInPath"},{"name":"sub_path","in":"path","required":true,"schema":{"type":"string"},"description":"Slash-separated nested key path within the resource document.","example":"plugins"}],"patch":{"tags":["Global Rules"],"operationId":"patchGlobalRulesSubPath","summary":"Replace a single nested field of a global rule","description":"Replaces the value at `sub_path` within the global rule document with the request body. The body is any valid JSON value, not necessarily an object. The updated complete resource must pass validation.","parameters":[{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{},"example":{"limit-count":{"count":100,"time_window":60,"rejected_code":429}}}}},"responses":{"200":{"description":"Sub-field replaced."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/apisix/admin/plugin_configs/{id}/{sub_path}":{"parameters":[{"$ref":"#/components/parameters/IdInPath"},{"name":"sub_path","in":"path","required":true,"schema":{"type":"string"},"description":"Slash-separated nested key path within the resource document.","example":"plugins"}],"patch":{"tags":["Plugin Configs"],"operationId":"patchPluginConfigsSubPath","summary":"Replace a single nested field of a plugin config","description":"Replaces the value at `sub_path` within the plugin config document with the request body. The body is any valid JSON value, not necessarily an object. The updated complete resource must pass validation.","parameters":[{"$ref":"#/components/parameters/Ttl"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{},"example":{"limit-count":{"count":100,"time_window":60,"rejected_code":429}}}}},"responses":{"200":{"description":"Sub-field replaced."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/apisix/admin/secrets/{secret_type}":{"parameters":[{"$ref":"#/components/parameters/SecretType"}],"get":{"tags":["Secrets"],"operationId":"listSecretsByType","summary":"List secrets of a single secret-manager type","description":"Returns secrets registered under the given manager (`vault`, `aws`, or `gcp`). For listing across all managers, use `GET /apisix/admin/secrets`.","parameters":[],"responses":{"200":{"description":"Paginated list of secrets for this manager.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"list":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/apisix/admin/secrets/{secret_type}/{id}/{sub_path}":{"parameters":[{"name":"secret_type","in":"path","required":true,"schema":{"type":"string","enum":["vault","aws","gcp"]},"description":"Secret manager backend.","example":"gcp"},{"$ref":"#/components/parameters/IdInPath"},{"name":"sub_path","in":"path","required":true,"schema":{"type":"string"},"description":"Slash-separated nested key path within the resource document.","example":"auth_config"}],"patch":{"tags":["Secrets"],"operationId":"patchSecretSubPath","summary":"Replace a single nested field of a secret","description":"Replaces the value at `sub_path` within the secret document with the request body. The body is any valid JSON value, not necessarily an object. The updated complete resource must pass validation.","requestBody":{"required":true,"content":{"application/json":{"schema":{},"example":{"client_email":"apisix@example.iam.gserviceaccount.com","private_key":"example-private-key","project_id":"example-project"}}}},"responses":{"200":{"description":"Sub-field replaced."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"parameters":[{"$ref":"#/components/parameters/Ttl"}]}},"/apisix/admin/schema/{resource}":{"parameters":[{"$ref":"#/components/parameters/ResourceKindInPath"}],"get":{"tags":["Schema Validation"],"operationId":"getResourceSchema","summary":"Get the JSON Schema of a built-in resource","description":"Returns the JSON Schema document used internally by APISIX to validate the named resource type.","responses":{"200":{"description":"JSON Schema document.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"parameters":[]}},"/apisix/admin/schema/plugins/{plugin_name}":{"parameters":[{"$ref":"#/components/parameters/PluginNameInPath"}],"get":{"tags":["Schema Validation"],"operationId":"getPluginSchemaAlt","summary":"Get a plugin's JSON Schema (alternative path)","description":"Equivalent to `GET /apisix/admin/plugins/{plugin_name}`. Provided for symmetry with `GET /apisix/admin/schema/{resource}`.","responses":{"200":{"description":"Plugin JSON Schema.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"parameters":[]}}},"servers":[{"url":"{protocol}://{host}:{port}","description":"APISIX Admin API Server","variables":{"protocol":{"default":"http","enum":["http","https"],"description":"Protocol scheme. Use `https` if `admin_api_mtls` is configured."},"host":{"default":"127.0.0.1","description":"Admin API host address. Configure via `deployment.admin.admin_listen` in `config.yaml`."},"port":{"default":"9180","description":"Admin API port. Default is `9180`."}}}],"components":{"securitySchemes":{"adminKey":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"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`."},"apiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"Admin API key passed as a query parameter. Convenient for `curl` experiments, but avoid in production — keys may be logged."},"apiKeyCookie":{"type":"apiKey","in":"cookie","name":"x_api_key","description":"Admin API key passed in a cookie."}},"schemas":{"ErrorResponse":{"type":"object","description":"Standard error response returned by the APISIX Admin API.","required":["error_msg"],"properties":{"error_msg":{"type":"string","description":"Human-readable error message describing what went wrong.","examples":["invalid configuration: property \"uri\" is required"]}},"examples":[{"error_msg":"invalid configuration: property \"uri\" is required"}]},"AuthErrorResponse":{"type":"object","description":"Authentication error returned when the API key is missing or invalid.","required":["error_msg"],"properties":{"error_msg":{"type":"string","description":"Authentication error message.","examples":["failed to check token"]},"description":{"type":"string","description":"Detailed reason for the authentication failure.","examples":["missing apikey"]}},"examples":[{"error_msg":"failed to check token","description":"missing apikey"}]},"NotFoundResponse":{"type":"object","description":"Returned when the requested resource does not exist.","required":["error_msg"],"properties":{"error_msg":{"type":"string","description":"Error message indicating the resource was not found.","examples":["Key not found"]}},"examples":[{"error_msg":"Key not found"}]},"ResourceId":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":"integer","minimum":1,"examples":[1],"title":"Integer ID"}]},"Timeout":{"type":"object","description":"Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.","required":["connect","send","read"],"properties":{"connect":{"type":"number","exclusiveMinimum":0,"description":"Timeout in seconds for establishing a connection to the upstream.","examples":[6]},"send":{"type":"number","exclusiveMinimum":0,"description":"Timeout in seconds for sending data to the upstream.","examples":[6]},"read":{"type":"number","exclusiveMinimum":0,"description":"Timeout in seconds for reading the response from the upstream.","examples":[6]}},"examples":[{"connect":6,"send":6,"read":6}]},"Labels":{"type":"object","description":"Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).","additionalProperties":{"type":"string","pattern":"^\\S+$","maxLength":256,"minLength":1},"examples":[{"env":"production","team":"platform","version":"v2"}]},"HealthCheckActiveHealthy":{"type":"object","description":"Thresholds for considering a target healthy during active checks.","properties":{"interval":{"type":"integer","minimum":1,"default":1,"description":"Interval in seconds between active health check probes for healthy targets."},"http_statuses":{"type":"array","items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[200,302],"description":"HTTP status codes that indicate a healthy target."},"successes":{"type":"integer","minimum":1,"maximum":254,"default":2,"description":"Number of consecutive successful probes to consider a target healthy."}}},"HealthCheckActiveUnhealthy":{"type":"object","description":"Thresholds for considering a target unhealthy during active checks.","properties":{"interval":{"type":"integer","minimum":1,"default":1,"description":"Interval in seconds between active health check probes for unhealthy targets."},"http_statuses":{"type":"array","items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[429,404,500,501,502,503,504,505],"description":"HTTP status codes that indicate an unhealthy target."},"http_failures":{"type":"integer","minimum":1,"maximum":254,"default":5,"description":"Number of HTTP failures to consider a target unhealthy."},"tcp_failures":{"type":"integer","minimum":1,"maximum":254,"default":2,"description":"Number of TCP connection failures to consider a target unhealthy."},"timeouts":{"type":"integer","minimum":1,"maximum":254,"default":3,"description":"Number of probe timeouts to consider a target unhealthy."}}},"HealthCheckActive":{"type":"object","description":"Active health check configuration. APISIX periodically sends probes to upstream nodes to determine their health status.","properties":{"type":{"type":"string","enum":["http","https","tcp"],"default":"http","description":"Protocol type for health check probes."},"timeout":{"type":"number","default":1,"description":"Timeout in seconds for each health check probe."},"concurrency":{"type":"integer","default":10,"description":"Number of targets to check concurrently during active health checks."},"host":{"type":"string","description":"Hostname to use in the health check probe `Host` header. Defaults to the upstream node's host."},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"Port to use for health check probes. Defaults to the upstream node's port."},"http_path":{"type":"string","default":"/","description":"HTTP request path for health check probes."},"https_verify_certificate":{"type":"boolean","default":true,"description":"Whether to verify the upstream's TLS certificate during HTTPS health checks."},"req_headers":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Additional HTTP headers to include in health check probe requests."},"healthy":{"$ref":"#/components/schemas/HealthCheckActiveHealthy"},"unhealthy":{"$ref":"#/components/schemas/HealthCheckActiveUnhealthy"}}},"HealthCheckPassiveHealthy":{"type":"object","description":"Thresholds for considering a target healthy based on real traffic responses.","properties":{"http_statuses":{"type":"array","items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[200,201,202,203,204,205,206,207,208,226,300,301,302,303,304,305,306,307,308],"description":"HTTP status codes from real traffic that indicate a healthy target."},"successes":{"type":"integer","minimum":0,"maximum":254,"default":5,"description":"Number of consecutive successful requests to restore a target to healthy status."}}},"HealthCheckPassiveUnhealthy":{"type":"object","description":"Thresholds for considering a target unhealthy based on real traffic responses.","properties":{"http_statuses":{"type":"array","items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[429,500,503],"description":"HTTP status codes from real traffic that indicate an unhealthy target."},"tcp_failures":{"type":"integer","minimum":0,"maximum":254,"default":2,"description":"Number of TCP failures from real traffic to consider a target unhealthy."},"timeouts":{"type":"integer","minimum":0,"maximum":254,"default":7,"description":"Number of timeouts from real traffic to consider a target unhealthy."},"http_failures":{"type":"integer","minimum":0,"maximum":254,"default":5,"description":"Number of HTTP failures from real traffic to consider a target unhealthy."}}},"HealthCheckPassive":{"type":"object","description":"Passive health check configuration. APISIX monitors real traffic responses to determine upstream node health — no extra probes are sent.","properties":{"type":{"type":"string","enum":["http","https","tcp"],"default":"http","description":"Protocol type for passive health monitoring."},"healthy":{"$ref":"#/components/schemas/HealthCheckPassiveHealthy"},"unhealthy":{"$ref":"#/components/schemas/HealthCheckPassiveUnhealthy"}}},"HealthCheck":{"type":"object","description":"Health check configuration for monitoring upstream node availability. Active checks require at least the `active` field.","properties":{"active":{"$ref":"#/components/schemas/HealthCheckActive"},"passive":{"$ref":"#/components/schemas/HealthCheckPassive"}},"anyOf":[{"required":["active"],"title":"Active Check"},{"required":["active","passive"],"title":"Passive Check"}]},"UpstreamNodesMap":{"type":"object","description":"Upstream nodes as a map of `\"host:port\": weight` pairs. This is the shorthand format.","additionalProperties":{"type":"integer","minimum":0,"description":"Weight of this node for load balancing. `0` means the node receives no traffic."},"examples":[{"httpbin.org:80":1,"10.0.0.1:8080":2}]},"UpstreamNodeItem":{"type":"object","description":"An upstream node with explicit host, port, weight, and optional priority.","required":["host","weight"],"properties":{"host":{"type":"string","description":"Hostname or IP address of the upstream node.","examples":["10.0.0.1"]},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"Port of the upstream node.","examples":[8080]},"weight":{"type":"integer","minimum":0,"description":"Weight for load balancing. Higher values mean more traffic. `0` means no traffic.","examples":[1]},"priority":{"type":"integer","default":0,"description":"Priority of the node. Nodes with higher priority are used first. Lower-priority nodes serve as fallbacks."},"metadata":{"type":"object","description":"Arbitrary metadata associated with this node."}}},"UpstreamNodes":{"description":"Upstream backend nodes. Supports two formats:\n\n**Map format** (shorthand): `{\"host:port\": weight}`\n\n**Array format** (full control): `[{\"host\": \"...\", \"port\": ..., \"weight\": ...}]`","anyOf":[{"$ref":"#/components/schemas/UpstreamNodesMap","title":"Weight Mapping"},{"type":"array","items":{"$ref":"#/components/schemas/UpstreamNodeItem"},"title":"Node Objects"}]},"UpstreamTLS":{"type":"object","description":"TLS configuration for connecting to upstream nodes over HTTPS/gRPCS.","properties":{"client_cert_id":{"$ref":"#/components/schemas/ResourceId","description":"ID of an SSL resource containing the client certificate. Mutually exclusive with `client_cert`/`client_key`."},"client_cert":{"type":"string","minLength":128,"maxLength":65536,"description":"PEM-encoded client certificate for mTLS with the upstream."},"client_key":{"type":"string","minLength":64,"maxLength":65536,"description":"PEM-encoded client private key for mTLS with the upstream."},"verify":{"type":"boolean","description":"Whether to verify the upstream server certificate. If omitted for HTTPS/gRPCS, follows the NGINX verification setting, which is off unless enabled. Explicit `false` disables verification. For `wss`, explicitly set `true` to enable verification against the shared trust store."},"ca_certs":{"type":"array","minItems":1,"items":{"type":"string","minLength":128,"maxLength":65536},"description":"PEM-encoded CA certificates for HTTPS/gRPCS upstream verification. Replaces the NGINX trust store for this upstream. If omitted, configure and load the shared store using `proxy_ssl_verify` for HTTPS or `grpc_ssl_verify` for gRPCS. See [Configure Upstream HTTPS](/apisix/how-to-guide/traffic-management/tls-and-mtls/configure-upstream-https). Does not enable verification by itself; set `tls.verify` to `true`. Rejected for `ws` and `wss` upstreams."}}},"KeepalivePool":{"type":"object","description":"Connection pool configuration for keepalive connections to upstream nodes.","properties":{"size":{"type":"integer","default":320,"minimum":1,"description":"Maximum number of keepalive connections cached in the connection pool."},"idle_timeout":{"type":"number","default":60,"minimum":0,"description":"Time in seconds after which an idle keepalive connection is closed. `0` disables the timeout."},"requests":{"type":"integer","default":1000,"minimum":1,"description":"Maximum number of requests that can be sent over a single keepalive connection before it is closed."}}},"Upstream":{"type":"object","description":"Upstream configuration defining backend service nodes and load balancing behavior.\n\nAn upstream must specify either `nodes` (static list) or `service_name` + `discovery_type` (service discovery).","properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","maxLength":256,"minLength":1,"description":"Human-readable name for the upstream."},"desc":{"type":"string","maxLength":256,"description":"Description of the upstream."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","description":"Unix timestamp when the upstream was created. Read-only, set automatically.","readOnly":true},"update_time":{"type":"integer","description":"Unix timestamp when the upstream was last updated. Read-only, set automatically.","readOnly":true},"nodes":{"description":"The upstream endpoints.","allOf":[{"$ref":"#/components/schemas/UpstreamNodes"}]},"warm_up_conf":{"$ref":"#/components/schemas/UpstreamWarmUp"},"retries":{"type":"integer","minimum":0,"description":"Number of retry attempts when a request to the upstream fails."},"retry_timeout":{"type":"number","minimum":0,"description":"Maximum time in seconds for retry attempts. `0` disables the retry timeout."},"timeout":{"$ref":"#/components/schemas/Timeout"},"type":{"type":"string","default":"roundrobin","enum":["roundrobin","chash","ewma","least_conn"],"description":"Load balancing algorithm.","x-enumDescriptions":{"roundrobin":"Weighted round-robin distribution (default).","chash":"Consistent hashing for session affinity.","ewma":"Latency-based load balancing using an exponentially weighted moving average.","least_conn":"Least number of active connections."}},"hash_on":{"type":"string","default":"vars","enum":["vars","header","cookie","consumer","vars_combinations"],"description":"What to hash on when `type` is `chash`.","x-enumDescriptions":{"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":{"type":"string","description":"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":{"type":"string","default":"http","enum":["grpc","grpcs","http","https","ws","wss","tcp","tls","udp","kafka"],"description":"Protocol for communicating with upstream nodes.","x-enumDescriptions":{"grpc":"Layer 7 gRPC.","grpcs":"Layer 7 gRPC over TLS.","http":"Layer 7 HTTP.","https":"Layer 7 HTTP over TLS.","tcp":"Layer 4 TCP.","tls":"Layer 4 TCP over TLS.","udp":"Layer 4 UDP.","kafka":"Apache Kafka protocol.","ws":"Frame-aware WebSocket proxying; `enable_websocket` is ignored.","wss":"Frame-aware WebSocket proxying over TLS; uses the shared CA trust store, not `tls.ca_certs`."}},"checks":{"$ref":"#/components/schemas/HealthCheck"},"tls":{"$ref":"#/components/schemas/UpstreamTLS"},"keepalive_pool":{"$ref":"#/components/schemas/KeepalivePool"},"pass_host":{"type":"string","enum":["pass","node","rewrite"],"default":"pass","description":"How to set the `Host` header when proxying to the upstream.","x-enumDescriptions":{"pass":"Forward the client's original `Host` header.","node":"Use the upstream node's hostname.","rewrite":"Use the value of `upstream_host`."}},"upstream_host":{"type":"string","description":"Custom `Host` header value. Only effective when `pass_host` is `rewrite`."},"discovery_type":{"type":"string","description":"Service discovery type (e.g., `dns`, `consul`, `nacos`, `eureka`). Required when using service discovery instead of static `nodes`."},"discovery_args":{"type":"object","description":"Additional arguments for service discovery.","properties":{"namespace_id":{"type":"string","description":"Namespace ID for Nacos service discovery."},"group_name":{"type":"string","description":"Group name for service discovery."}}},"service_name":{"type":"string","maxLength":256,"minLength":1,"description":"Service name for service discovery. Required when `discovery_type` is set."}},"oneOf":[{"required":["nodes"],"title":"Use Upstream Nodes"},{"required":["service_name","discovery_type"],"title":"Use Service Registry"}],"additionalProperties":false},"Plugins":{"type":"object","description":"Plugin configurations as a JSON object. Each key is a plugin name, and the value is that plugin's configuration object.\n\nExample:\n```json\n{\n  \"limit-count\": {\n    \"count\": 100,\n    \"time_window\": 60\n  },\n  \"key-auth\": {}\n}\n```\n\nSee the [Plugin Hub](https://docs.api7.ai/hub) for available plugins and their schemas.","additionalProperties":{"type":"object"},"examples":[{"limit-count":{"count":100,"time_window":60,"rejected_code":429,"key_type":"var","key":"remote_addr"}}]},"Route":{"type":"object","description":"Route configuration. A route matches incoming requests by URI, host, methods, and other conditions, then forwards them to an upstream.\n\nA route must have at least a `uri` (or `uris`) and one of: `upstream`, `upstream_id`, `service_id`, or `plugins`.","properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","maxLength":100,"minLength":1,"description":"Human-readable name for the route."},"desc":{"type":"string","maxLength":256,"description":"Description of what this route does."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"uri":{"type":"string","minLength":1,"maxLength":4096,"description":"URI path pattern to match. Supports exact match (`/api/v1/users`) and prefix match (`/api/*`). Mutually exclusive with `uris`.","examples":["/api/v1/users/*"]},"uris":{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"Multiple URI patterns. Mutually exclusive with `uri`."},"host":{"type":"string","description":"Single hostname to match against the request's `Host` header. Supports wildcard prefix (`*.example.com`). Mutually exclusive with `hosts`.","examples":["api.example.com"]},"hosts":{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"Multiple hostnames to match. Mutually exclusive with `host`."},"methods":{"type":"array","items":{"type":"string","enum":["GET","POST","PUT","DELETE","PATCH","HEAD","OPTIONS","CONNECT","TRACE","PURGE"]},"uniqueItems":true,"description":"HTTP methods allowed on this route. If empty or not set, all methods are allowed.","examples":[["GET","POST"]]},"remote_addr":{"type":"string","description":"Single client IP address or CIDR range to match. Mutually exclusive with `remote_addrs`.","examples":["192.168.1.0/24"]},"remote_addrs":{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"Multiple client IP addresses or CIDR ranges to match. Mutually exclusive with `remote_addr`."},"priority":{"type":"integer","default":0,"description":"Route priority. When multiple routes match the same request, the one with the highest priority wins."},"vars":{"type":"array","description":"Custom matching conditions using [APISIX expressions](https://docs.api7.ai/apisix/reference/router-options). Each condition is an array of `[variable, operator, value]`.","examples":[[["http_user_agent","~*","curl"]]],"items":{}},"filter_func":{"type":"string","minLength":10,"pattern":"^function","description":"Custom Lua function for advanced request matching. Must start with `function`."},"plugins":{"$ref":"#/components/schemas/Plugins"},"plugin_config_id":{"$ref":"#/components/schemas/ResourceId","description":"Reference to a Plugin Config resource. Cannot be used together with `script`."},"upstream":{"$ref":"#/components/schemas/Upstream"},"upstream_id":{"$ref":"#/components/schemas/ResourceId","description":"Reference to an existing Upstream resource."},"service_id":{"$ref":"#/components/schemas/ResourceId","description":"Reference to an existing Service resource."},"timeout":{"$ref":"#/components/schemas/Timeout"},"enable_websocket":{"type":"boolean","description":"Enable WebSocket proxying on this route."},"status":{"type":"integer","enum":[1,0],"default":1,"description":"Route status.","x-enumDescriptions":{"0":"Disabled.","1":"Enabled (default)."}},"script":{"type":"string","minLength":10,"maxLength":102400,"description":"Lua script for plugin orchestration. Cannot be used together with `plugins` or `plugin_config_id`."},"script_id":{"$ref":"#/components/schemas/ResourceId","description":"Script ID (used internally by APISIX Dashboard)."}},"additionalProperties":false,"anyOf":[{"title":"Plugin and URI required","required":["plugins","uri"]},{"title":"Upstream and URI required","required":["upstream","uri"]},{"title":"Upstream ID and URI required","required":["upstream_id","uri"]},{"title":"Service ID and URI required","required":["service_id","uri"]},{"title":"Plugin and URIs required","required":["plugins","uris"]},{"title":"Upstream and URIs required","required":["upstream","uris"]},{"title":"Upstream ID and URIs required","required":["upstream_id","uris"]},{"title":"Service ID and URIs required","required":["service_id","uris"]},{"title":"Script and URI required","required":["script","uri"]},{"title":"Script and URIs required","required":["script","uris"]}]},"Service":{"type":"object","description":"Service configuration. A service groups an upstream and plugins so multiple routes can share the same backend configuration.","properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","maxLength":256,"minLength":1,"description":"Human-readable name."},"desc":{"type":"string","maxLength":256,"description":"Description of this service."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"plugins":{"$ref":"#/components/schemas/Plugins"},"upstream":{"$ref":"#/components/schemas/Upstream"},"upstream_id":{"$ref":"#/components/schemas/ResourceId","description":"Reference to an existing Upstream resource."},"script":{"type":"string","minLength":10,"maxLength":102400,"description":"Lua script for plugin orchestration."},"enable_websocket":{"type":"boolean","description":"Enable WebSocket proxying for routes using this service."},"hosts":{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"Hostnames associated with this service."}},"additionalProperties":false},"Consumer":{"type":"object","description":"Consumer configuration. Represents an API user or application with authentication credentials and plugin policies.","required":["username"],"properties":{"username":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[a-zA-Z0-9_\\-]+$","description":"Unique username for the consumer. Only alphanumeric characters, hyphens, and underscores are allowed.","examples":["my-app"]},"desc":{"type":"string","maxLength":256,"description":"Description of this consumer."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"group_id":{"$ref":"#/components/schemas/ResourceId","description":"Reference to a Consumer Group for shared plugin configurations."},"plugins":{"$ref":"#/components/schemas/Plugins"}},"additionalProperties":false},"Credential":{"type":"object","description":"Credential configuration. Stores exactly one authentication plugin for a consumer.","properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","maxLength":256,"minLength":1,"description":"Human-readable name."},"desc":{"type":"string","maxLength":256,"description":"Description of this credential."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"plugins":{"type":"object","maxProperties":1,"description":"Exactly one authentication plugin configuration (e.g., `key-auth`, `basic-auth`, `jwt-auth`)."}},"additionalProperties":false},"ConsumerGroup":{"type":"object","description":"Consumer Group configuration. Defines shared plugin configurations for multiple consumers.","required":["plugins"],"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","maxLength":256,"minLength":1,"description":"Human-readable name."},"desc":{"type":"string","maxLength":256,"description":"Description of this group."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"plugins":{"$ref":"#/components/schemas/Plugins"}},"additionalProperties":false},"SSL":{"type":"object","description":"SSL certificate configuration for TLS termination or mTLS.","properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"desc":{"type":"string","maxLength":256,"description":"Description."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"type":{"type":"string","default":"server","enum":["server","client"],"description":"Certificate type.","x-enumDescriptions":{"server":"HTTPS termination matched by SNI.","client":"Client certificate for mTLS with upstream services."}},"sni":{"type":"string","description":"Server Name Indication (SNI) to match. Supports wildcard prefix (`*.example.com`). Mutually exclusive with `snis`.","examples":["api.example.com"]},"snis":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Multiple SNI hostnames. Mutually exclusive with `sni`."},"cert":{"type":"string","minLength":128,"maxLength":65536,"description":"PEM-encoded server certificate. Can also be a secret reference (`$secret://...`)."},"key":{"type":"string","minLength":128,"maxLength":65536,"description":"PEM-encoded private key. Can also be a secret reference (`$secret://...`). **Not returned in GET responses for security.**"},"certs":{"type":"array","items":{"type":"string"},"description":"Additional certificates for certificate chain or alternative key types."},"keys":{"type":"array","items":{"type":"string"},"description":"Additional private keys corresponding to `certs`."},"client":{"type":"object","description":"mTLS client verification settings.","required":["ca"],"properties":{"ca":{"type":"string","minLength":128,"maxLength":65536,"description":"PEM-encoded CA certificate for client verification."},"depth":{"type":"integer","minimum":0,"default":1,"description":"Maximum certificate chain depth."},"skip_mtls_uri_regex":{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"URI regex patterns to skip mTLS verification."}}},"status":{"type":"integer","enum":[1,0],"default":1,"description":"SSL status.","x-enumDescriptions":{"0":"Disabled.","1":"Enabled (default)."}},"ssl_protocols":{"type":"array","items":{"type":"string","enum":["TLSv1.1","TLSv1.2","TLSv1.3"]},"maxItems":3,"uniqueItems":true,"description":"Allowed TLS protocol versions."}},"additionalProperties":false,"if":{"properties":{"type":{"enum":["server"]}}},"then":{"oneOf":[{"title":"Single SNI","required":["sni","key","cert"]},{"title":"Multiple SNIs","required":["snis","key","cert"]}]},"else":{"title":"SNI not required"}},"GlobalRule":{"type":"object","description":"Global Rule configuration. Global plugins apply independently of locally bound plugins. For HTTP requests, execution is interleaved by phase: global `rewrite`, local `rewrite`, global `access`, then local `access`. Priorities order plugins within each phase and scope, and an early response skips handlers scheduled later.","required":["plugins"],"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"plugins":{"$ref":"#/components/schemas/Plugins"}},"additionalProperties":false},"PluginConfig":{"type":"object","description":"Plugin Config — a reusable set of plugin configurations that can be referenced by multiple routes.","required":["plugins"],"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","description":"Human-readable name."},"desc":{"type":"string","maxLength":256,"description":"Description."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"plugins":{"$ref":"#/components/schemas/Plugins"}},"additionalProperties":false},"StreamRoute":{"type":"object","description":"Stream Route for TCP/UDP (L4) proxying. Matches transport-layer connections by client IP, server address/port, or SNI.","properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","maxLength":256,"minLength":1,"description":"Human-readable name."},"desc":{"type":"string","maxLength":256,"description":"Description."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"remote_addr":{"type":"string","description":"Client IP address or CIDR range to match."},"server_addr":{"type":"string","description":"Server IP address to match."},"server_port":{"type":"integer","minimum":1,"maximum":65535,"description":"Server port to match."},"sni":{"type":"string","description":"SNI hostname to match. Supports wildcard hostnames. Mutually exclusive with `snis`.","pattern":"^\\*$|^\\*?[0-9a-zA-Z-._\\[\\]:]+$"},"upstream":{"$ref":"#/components/schemas/Upstream"},"upstream_id":{"$ref":"#/components/schemas/ResourceId","description":"Reference to an existing Upstream."},"service_id":{"$ref":"#/components/schemas/ResourceId","description":"Reference to an existing Service."},"plugins":{"$ref":"#/components/schemas/Plugins"},"snis":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","pattern":"^\\*$|^\\*?[0-9a-zA-Z-._\\[\\]:]+$"},"description":"Alternative SNI hostnames to match, including wildcard hostnames. Mutually exclusive with `sni`."},"tls_passthrough":{"type":"boolean","default":false,"description":"On a listener configured with both `tls` and `tls_passthrough`, `true` forwards encrypted TLS bytes to the upstream; `false` terminates TLS at APISIX. Ignored on dedicated listeners. Passthrough requires a TCP upstream, not scheme `tls`."}},"additionalProperties":false,"not":{"required":["sni","snis"]}},"Proto":{"type":"object","description":"Protocol buffer definition for gRPC transcoding.","required":["content"],"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","maxLength":256,"minLength":1,"description":"Human-readable name."},"desc":{"type":"string","maxLength":256,"description":"Description."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"content":{"type":"string","minLength":1,"maxLength":1048576,"description":"Protobuf `.proto` file content as a string."}},"additionalProperties":false},"SSLRead":{"type":"object","description":"SSL certificate configuration for TLS termination or mTLS.\n\n**Read-only response variant**: private keys (`key`, `keys`) are stripped from GET responses, so they are not present here.","properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"desc":{"type":"string","maxLength":256,"description":"Description."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"type":{"type":"string","default":"server","enum":["server","client"],"description":"Certificate type.","x-enumDescriptions":{"server":"HTTPS termination matched by SNI.","client":"Client certificate for mTLS with upstream services."}},"sni":{"type":"string","description":"Server Name Indication (SNI) to match. Supports wildcard prefix (`*.example.com`). Mutually exclusive with `snis`.","examples":["api.example.com"]},"snis":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Multiple SNI hostnames. Mutually exclusive with `sni`."},"cert":{"type":"string","minLength":128,"maxLength":65536,"description":"PEM-encoded server certificate. Can also be a secret reference (`$secret://...`)."},"key":{"type":"string","minLength":128,"maxLength":65536,"description":"PEM-encoded private key. Can also be a secret reference (`$secret://...`). **Not returned in GET responses for security.**"},"certs":{"type":"array","items":{"type":"string"},"description":"Additional certificates for certificate chain or alternative key types."},"keys":{"type":"array","items":{"type":"string"},"description":"Additional private keys corresponding to `certs`."},"client":{"type":"object","description":"mTLS client verification settings.","required":["ca"],"properties":{"ca":{"type":"string","minLength":128,"maxLength":65536,"description":"PEM-encoded CA certificate for client verification."},"depth":{"type":"integer","minimum":0,"default":1,"description":"Maximum certificate chain depth."},"skip_mtls_uri_regex":{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"URI regex patterns to skip mTLS verification."}}},"status":{"type":"integer","enum":[1,0],"default":1,"description":"SSL status.","x-enumDescriptions":{"0":"Disabled.","1":"Enabled (default)."}},"ssl_protocols":{"type":"array","items":{"type":"string","enum":["TLSv1.1","TLSv1.2","TLSv1.3"]},"maxItems":3,"uniqueItems":true,"description":"Allowed TLS protocol versions."}},"additionalProperties":false,"if":{"properties":{"type":{"enum":["server"]}}},"then":{"oneOf":[{"title":"Single SNI","required":["sni","cert"]},{"title":"Multiple SNIs","required":["snis","cert"]}]},"else":{"title":"SNI not required"}},"CredentialEnvelope":{"type":"object","description":"`Credential` wrapped in the etcd-style envelope.","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/Credential"},"createdIndex":{"type":"integer"},"modifiedIndex":{"type":"integer"}},"required":["key","value"]},"CredentialListEnvelope":{"type":"object","description":"Paginated list of `Credential` envelopes.","properties":{"total":{"type":"integer"},"list":{"type":"array","items":{"$ref":"#/components/schemas/CredentialEnvelope"}}},"required":["total","list"]},"RouteEnvelope":{"type":"object","description":"`Route` wrapped in the etcd-style envelope.","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/Route"},"createdIndex":{"type":"integer"},"modifiedIndex":{"type":"integer"}},"required":["key","value"]},"RouteListEnvelope":{"type":"object","description":"Paginated list of `Route` envelopes.","properties":{"total":{"type":"integer"},"list":{"type":"array","items":{"$ref":"#/components/schemas/RouteEnvelope"}}},"required":["total","list"]},"GraphQLCostDecoration":{"type":"object","description":"Cost decoration owned by a service and consumed by `graphql-limit-count`. Managed as a separate subresource, not an inline service field.","properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"service_id":{"$ref":"#/components/schemas/ResourceId","description":"ID of the owning service, set from the URL. Omit when creating or replacing; cannot be patched."},"field_path":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*$","description":"Position in the GraphQL schema. A type name weights fields returning that type; a type and field name weights that field; further segments restrict the selection chain. `Query` or `Mutation` alone weights the whole operation.","examples":["Query.products","Product.reviews"]},"add_value":{"type":"number","minimum":0,"default":1,"description":"The node's own cost."},"add_arguments":{"type":"array","items":{"type":"string","minLength":1},"description":"Arguments whose values are added to `add_value`."},"mul_value":{"type":"number","minimum":0,"default":1,"description":"Multiplier applied to the cost of selected children."},"mul_arguments":{"type":"array","items":{"type":"string","minLength":1},"description":"Arguments whose values multiply `mul_value`. Under `node_quantifier`, these quantifiers carry to deeper quantified nodes."},"name":{"type":"string","maxLength":256,"minLength":1},"desc":{"type":"string","maxLength":256},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true},"update_time":{"type":"integer","readOnly":true}},"required":["field_path"],"additionalProperties":false},"GraphQLCostDecorationCreate":{"type":"object","description":"Request to create a decoration with an automatically generated ID. Omit `id` and timestamps. Ownership comes from the service ID in the URL.","properties":{"service_id":{"$ref":"#/components/schemas/ResourceId","description":"ID of the owning service, set from the URL. Omit when creating or replacing; cannot be patched."},"field_path":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*$","description":"Position in the GraphQL schema. A type name weights fields returning that type; a type and field name weights that field; further segments restrict the selection chain. `Query` or `Mutation` alone weights the whole operation.","examples":["Query.products","Product.reviews"]},"add_value":{"type":"number","minimum":0,"default":1,"description":"The node's own cost."},"add_arguments":{"type":"array","items":{"type":"string","minLength":1},"description":"Arguments whose values are added to `add_value`."},"mul_value":{"type":"number","minimum":0,"default":1,"description":"Multiplier applied to the cost of selected children."},"mul_arguments":{"type":"array","items":{"type":"string","minLength":1},"description":"Arguments whose values multiply `mul_value`. Under `node_quantifier`, these quantifiers carry to deeper quantified nodes."},"name":{"type":"string","maxLength":256,"minLength":1},"desc":{"type":"string","maxLength":256},"labels":{"$ref":"#/components/schemas/Labels"}},"required":["field_path"],"additionalProperties":false},"GraphQLCostDecorationPatch":{"type":"object","description":"Fields to merge into an existing decoration. Omitted fields retain their current values. The `id`, if supplied, must match the URL.","properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"create_time":{"type":"integer"},"update_time":{"type":"integer"},"field_path":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*$","description":"Position in the GraphQL schema. A type name weights fields returning that type; a type and field name weights that field; further segments restrict the selection chain. `Query` or `Mutation` alone weights the whole operation.","examples":["Query.products","Product.reviews"]},"add_value":{"type":"number","minimum":0,"description":"The node's own cost."},"add_arguments":{"type":"array","items":{"type":"string","minLength":1},"description":"Arguments whose values are added to `add_value`."},"mul_value":{"type":"number","minimum":0,"description":"Multiplier applied to the cost of selected children."},"mul_arguments":{"type":"array","items":{"type":"string","minLength":1},"description":"Arguments whose values multiply `mul_value`. Under `node_quantifier`, these quantifiers carry to deeper quantified nodes."},"name":{"type":"string","maxLength":256,"minLength":1},"desc":{"type":"string","maxLength":256},"labels":{"$ref":"#/components/schemas/Labels"}},"additionalProperties":false},"GraphQLCostDecorationEnvelope":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/GraphQLCostDecoration"},"createdIndex":{"type":"integer"},"modifiedIndex":{"type":"integer"}},"required":["key","value"]},"GraphQLCostDecorationListEnvelope":{"type":"object","properties":{"total":{"type":"integer"},"list":{"type":"array","items":{"$ref":"#/components/schemas/GraphQLCostDecorationEnvelope"}}},"required":["total","list"]},"ServiceEnvelope":{"type":"object","description":"`Service` wrapped in the etcd-style envelope.","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/Service"},"createdIndex":{"type":"integer"},"modifiedIndex":{"type":"integer"}},"required":["key","value"]},"ServiceListEnvelope":{"type":"object","description":"Paginated list of `Service` envelopes.","properties":{"total":{"type":"integer"},"list":{"type":"array","items":{"$ref":"#/components/schemas/ServiceEnvelope"}}},"required":["total","list"]},"UpstreamEnvelope":{"type":"object","description":"`Upstream` wrapped in the etcd-style envelope.","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/Upstream"},"createdIndex":{"type":"integer"},"modifiedIndex":{"type":"integer"}},"required":["key","value"]},"UpstreamListEnvelope":{"type":"object","description":"Paginated list of `Upstream` envelopes.","properties":{"total":{"type":"integer"},"list":{"type":"array","items":{"$ref":"#/components/schemas/UpstreamEnvelope"}}},"required":["total","list"]},"ConsumerEnvelope":{"type":"object","description":"`Consumer` wrapped in the etcd-style envelope.","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/Consumer"},"createdIndex":{"type":"integer"},"modifiedIndex":{"type":"integer"}},"required":["key","value"]},"ConsumerListEnvelope":{"type":"object","description":"Paginated list of `Consumer` envelopes.","properties":{"total":{"type":"integer"},"list":{"type":"array","items":{"$ref":"#/components/schemas/ConsumerEnvelope"}}},"required":["total","list"]},"ConsumerGroupEnvelope":{"type":"object","description":"`ConsumerGroup` wrapped in the etcd-style envelope.","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/ConsumerGroup"},"createdIndex":{"type":"integer"},"modifiedIndex":{"type":"integer"}},"required":["key","value"]},"ConsumerGroupListEnvelope":{"type":"object","description":"Paginated list of `ConsumerGroup` envelopes.","properties":{"total":{"type":"integer"},"list":{"type":"array","items":{"$ref":"#/components/schemas/ConsumerGroupEnvelope"}}},"required":["total","list"]},"SSLEnvelope":{"type":"object","description":"`SSLRead` wrapped in the etcd-style envelope.","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/SSLRead"},"createdIndex":{"type":"integer"},"modifiedIndex":{"type":"integer"}},"required":["key","value"]},"SSLListEnvelope":{"type":"object","description":"Paginated list of `SSLRead` envelopes.","properties":{"total":{"type":"integer"},"list":{"type":"array","items":{"$ref":"#/components/schemas/SSLEnvelope"}}},"required":["total","list"]},"GlobalRuleEnvelope":{"type":"object","description":"`GlobalRule` wrapped in the etcd-style envelope.","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/GlobalRule"},"createdIndex":{"type":"integer"},"modifiedIndex":{"type":"integer"}},"required":["key","value"]},"GlobalRuleListEnvelope":{"type":"object","description":"Paginated list of `GlobalRule` envelopes.","properties":{"total":{"type":"integer"},"list":{"type":"array","items":{"$ref":"#/components/schemas/GlobalRuleEnvelope"}}},"required":["total","list"]},"PluginConfigEnvelope":{"type":"object","description":"`PluginConfig` wrapped in the etcd-style envelope.","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/PluginConfig"},"createdIndex":{"type":"integer"},"modifiedIndex":{"type":"integer"}},"required":["key","value"]},"PluginConfigListEnvelope":{"type":"object","description":"Paginated list of `PluginConfig` envelopes.","properties":{"total":{"type":"integer"},"list":{"type":"array","items":{"$ref":"#/components/schemas/PluginConfigEnvelope"}}},"required":["total","list"]},"StreamRouteEnvelope":{"type":"object","description":"`StreamRoute` wrapped in the etcd-style envelope.","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/StreamRoute"},"createdIndex":{"type":"integer"},"modifiedIndex":{"type":"integer"}},"required":["key","value"]},"StreamRouteListEnvelope":{"type":"object","description":"Paginated list of `StreamRoute` envelopes.","properties":{"total":{"type":"integer"},"list":{"type":"array","items":{"$ref":"#/components/schemas/StreamRouteEnvelope"}}},"required":["total","list"]},"ProtoEnvelope":{"type":"object","description":"`Proto` wrapped in the etcd-style envelope.","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/Proto"},"createdIndex":{"type":"integer"},"modifiedIndex":{"type":"integer"}},"required":["key","value"]},"ProtoListEnvelope":{"type":"object","description":"Paginated list of `Proto` envelopes.","properties":{"total":{"type":"integer"},"list":{"type":"array","items":{"$ref":"#/components/schemas/ProtoEnvelope"}}},"required":["total","list"]},"RoutePatch":{"type":"object","description":"Partial update for an existing `Route`. APISIX recursively merges object fields, replaces arrays, and removes an object field when its value is `null`. The merged resource is then validated against the complete `Route` schema.","properties":{"id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"name":{"type":["string","null"],"maxLength":100,"minLength":1,"description":"Human-readable name for the route."},"desc":{"type":["string","null"],"maxLength":256,"description":"Description of what this route does."},"labels":{"type":["object","null"],"description":"Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).","additionalProperties":{"type":["string","null"],"pattern":"^\\S+$","maxLength":256,"minLength":1},"examples":[{"env":"production","team":"platform","version":"v2"}]},"create_time":{"type":["integer","null"],"readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":["integer","null"],"readOnly":true,"description":"Unix timestamp of last update. Read-only."},"uri":{"type":["string","null"],"minLength":1,"maxLength":4096,"description":"URI path pattern to match. Supports exact match (`/api/v1/users`) and prefix match (`/api/*`). Mutually exclusive with `uris`.","examples":["/api/v1/users/*"]},"uris":{"type":["array","null"],"items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"Multiple URI patterns. Mutually exclusive with `uri`."},"host":{"type":["string","null"],"description":"Single hostname to match against the request's `Host` header. Supports wildcard prefix (`*.example.com`). Mutually exclusive with `hosts`.","examples":["api.example.com"]},"hosts":{"type":["array","null"],"items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"Multiple hostnames to match. Mutually exclusive with `host`."},"methods":{"type":["array","null"],"items":{"type":"string","enum":["GET","POST","PUT","DELETE","PATCH","HEAD","OPTIONS","CONNECT","TRACE","PURGE"]},"uniqueItems":true,"description":"HTTP methods allowed on this route. If empty or not set, all methods are allowed.","examples":[["GET","POST"]]},"remote_addr":{"type":["string","null"],"description":"Single client IP address or CIDR range to match. Mutually exclusive with `remote_addrs`.","examples":["192.168.1.0/24"]},"remote_addrs":{"type":["array","null"],"items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"Multiple client IP addresses or CIDR ranges to match. Mutually exclusive with `remote_addr`."},"priority":{"type":["integer","null"],"default":0,"description":"Route priority. When multiple routes match the same request, the one with the highest priority wins."},"vars":{"type":["array","null"],"description":"Custom matching conditions using [APISIX expressions](https://docs.api7.ai/apisix/reference/router-options). Each condition is an array of `[variable, operator, value]`.","examples":[[["http_user_agent","~*","curl"]]],"items":{}},"filter_func":{"type":["string","null"],"minLength":10,"pattern":"^function","description":"Custom Lua function for advanced request matching. Must start with `function`."},"plugins":{"type":["object","null"],"description":"Plugin configurations as a JSON object. Each key is a plugin name, and the value is that plugin's configuration object.\n\nExample:\n```json\n{\n  \"limit-count\": {\n    \"count\": 100,\n    \"time_window\": 60\n  },\n  \"key-auth\": {}\n}\n```\n\nSee the [Plugin Hub](https://docs.api7.ai/hub) for available plugins and their schemas.","additionalProperties":{"type":["object","null"]},"examples":[{"limit-count":{"count":100,"time_window":60,"rejected_code":429,"key_type":"var","key":"remote_addr"}}]},"plugin_config_id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"upstream":{"type":["object","null"],"description":"Upstream configuration defining backend service nodes and load balancing behavior.\n\nAn upstream must specify either `nodes` (static list) or `service_name` + `discovery_type` (service discovery).","properties":{"id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"name":{"type":["string","null"],"maxLength":256,"minLength":1,"description":"Human-readable name for the upstream."},"desc":{"type":["string","null"],"maxLength":256,"description":"Description of the upstream."},"labels":{"type":["object","null"],"description":"Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).","additionalProperties":{"type":["string","null"],"pattern":"^\\S+$","maxLength":256,"minLength":1},"examples":[{"env":"production","team":"platform","version":"v2"}]},"create_time":{"type":["integer","null"],"description":"Unix timestamp when the upstream was created. Read-only, set automatically.","readOnly":true},"update_time":{"type":["integer","null"],"description":"Unix timestamp when the upstream was last updated. Read-only, set automatically.","readOnly":true},"nodes":{"description":"The upstream endpoints.","anyOf":[{"description":"Upstream backend nodes. Supports two formats:\n\n**Map format** (shorthand): `{\"host:port\": weight}`\n\n**Array format** (full control): `[{\"host\": \"...\", \"port\": ..., \"weight\": ...}]`","anyOf":[{"type":["object","null"],"description":"Upstream nodes as a map of `\"host:port\": weight` pairs. This is the shorthand format.","additionalProperties":{"type":["integer","null"],"minimum":0,"description":"Weight of this node for load balancing. `0` means the node receives no traffic."},"examples":[{"httpbin.org:80":1,"10.0.0.1:8080":2}]},{"type":["array","null"],"items":{"$ref":"#/components/schemas/UpstreamNodeItem"},"title":"Node Objects"},{"type":"null"},{"type":"null"}]},{"type":"null"},{"type":"null"}]},"warm_up_conf":{"type":["object","null"],"description":"Gradually increases the effective weight of newly observed nodes. Only supported for HTTP upstreams using `roundrobin` and a single node priority; ignored by stream routes and rejected in inline `traffic-split` upstreams. The initial node set is already warmed. Each gateway instance tracks ramps independently. This changes traffic distribution, not the total request rate.","properties":{"slow_start_time_seconds":{"type":["integer","null"],"minimum":1,"description":"Seconds for a new node to reach its configured weight."},"min_weight_percent":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Minimum percentage of the configured node weight. Effective positive weights are rounded down but never below 1."},"interval":{"type":["integer","null"],"minimum":1,"default":1,"description":"Seconds between weight refreshes. Cannot exceed `slow_start_time_seconds`."},"aggression":{"type":["number","null"],"minimum":0.01,"default":1,"description":"Ramp shape: 1 is linear, above 1 is faster initially, and below 1 is slower initially."},"startup_grace_period_seconds":{"type":["integer","null"],"minimum":0,"default":0,"description":"Seconds after the gateway starts during which newly observed nodes are treated as already warmed."}},"additionalProperties":false},"retries":{"type":["integer","null"],"minimum":0,"description":"Number of retry attempts when a request to the upstream fails."},"retry_timeout":{"type":["number","null"],"minimum":0,"description":"Maximum time in seconds for retry attempts. `0` disables the retry timeout."},"timeout":{"type":["object","null"],"description":"Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.","properties":{"connect":{"type":["number","null"],"exclusiveMinimum":0,"description":"Timeout in seconds for establishing a connection to the upstream.","examples":[6]},"send":{"type":["number","null"],"exclusiveMinimum":0,"description":"Timeout in seconds for sending data to the upstream.","examples":[6]},"read":{"type":["number","null"],"exclusiveMinimum":0,"description":"Timeout in seconds for reading the response from the upstream.","examples":[6]}},"examples":[{"connect":6,"send":6,"read":6}]},"type":{"type":["string","null"],"default":"roundrobin","enum":["roundrobin","chash","ewma","least_conn",null],"description":"Load balancing algorithm.","x-enumDescriptions":{"roundrobin":"Weighted round-robin distribution (default).","chash":"Consistent hashing for session affinity.","ewma":"Latency-based load balancing using an exponentially weighted moving average.","least_conn":"Least number of active connections."}},"hash_on":{"type":["string","null"],"default":"vars","enum":["vars","header","cookie","consumer","vars_combinations",null],"description":"What to hash on when `type` is `chash`.","x-enumDescriptions":{"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":{"type":["string","null"],"description":"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":{"type":["string","null"],"default":"http","enum":["grpc","grpcs","http","https","ws","wss","tcp","tls","udp","kafka",null],"description":"Protocol for communicating with upstream nodes.","x-enumDescriptions":{"grpc":"Layer 7 gRPC.","grpcs":"Layer 7 gRPC over TLS.","http":"Layer 7 HTTP.","https":"Layer 7 HTTP over TLS.","tcp":"Layer 4 TCP.","tls":"Layer 4 TCP over TLS.","udp":"Layer 4 UDP.","kafka":"Apache Kafka protocol.","ws":"Frame-aware WebSocket proxying; `enable_websocket` is ignored.","wss":"Frame-aware WebSocket proxying over TLS; uses the shared CA trust store, not `tls.ca_certs`."}},"checks":{"type":["object","null"],"description":"Health check configuration for monitoring upstream node availability. Active checks require at least the `active` field.","properties":{"active":{"type":["object","null"],"description":"Active health check configuration. APISIX periodically sends probes to upstream nodes to determine their health status.","properties":{"type":{"type":["string","null"],"enum":["http","https","tcp",null],"default":"http","description":"Protocol type for health check probes."},"timeout":{"type":["number","null"],"default":1,"description":"Timeout in seconds for each health check probe."},"concurrency":{"type":["integer","null"],"default":10,"description":"Number of targets to check concurrently during active health checks."},"host":{"type":["string","null"],"description":"Hostname to use in the health check probe `Host` header. Defaults to the upstream node's host."},"port":{"type":["integer","null"],"minimum":1,"maximum":65535,"description":"Port to use for health check probes. Defaults to the upstream node's port."},"http_path":{"type":["string","null"],"default":"/","description":"HTTP request path for health check probes."},"https_verify_certificate":{"type":["boolean","null"],"default":true,"description":"Whether to verify the upstream's TLS certificate during HTTPS health checks."},"req_headers":{"type":["array","null"],"items":{"type":"string"},"minItems":1,"description":"Additional HTTP headers to include in health check probe requests."},"healthy":{"type":["object","null"],"description":"Thresholds for considering a target healthy during active checks.","properties":{"interval":{"type":["integer","null"],"minimum":1,"default":1,"description":"Interval in seconds between active health check probes for healthy targets."},"http_statuses":{"type":["array","null"],"items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[200,302],"description":"HTTP status codes that indicate a healthy target."},"successes":{"type":["integer","null"],"minimum":1,"maximum":254,"default":2,"description":"Number of consecutive successful probes to consider a target healthy."}}},"unhealthy":{"type":["object","null"],"description":"Thresholds for considering a target unhealthy during active checks.","properties":{"interval":{"type":["integer","null"],"minimum":1,"default":1,"description":"Interval in seconds between active health check probes for unhealthy targets."},"http_statuses":{"type":["array","null"],"items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[429,404,500,501,502,503,504,505],"description":"HTTP status codes that indicate an unhealthy target."},"http_failures":{"type":["integer","null"],"minimum":1,"maximum":254,"default":5,"description":"Number of HTTP failures to consider a target unhealthy."},"tcp_failures":{"type":["integer","null"],"minimum":1,"maximum":254,"default":2,"description":"Number of TCP connection failures to consider a target unhealthy."},"timeouts":{"type":["integer","null"],"minimum":1,"maximum":254,"default":3,"description":"Number of probe timeouts to consider a target unhealthy."}}}}},"passive":{"type":["object","null"],"description":"Passive health check configuration. APISIX monitors real traffic responses to determine upstream node health — no extra probes are sent.","properties":{"type":{"type":["string","null"],"enum":["http","https","tcp",null],"default":"http","description":"Protocol type for passive health monitoring."},"healthy":{"type":["object","null"],"description":"Thresholds for considering a target healthy based on real traffic responses.","properties":{"http_statuses":{"type":["array","null"],"items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[200,201,202,203,204,205,206,207,208,226,300,301,302,303,304,305,306,307,308],"description":"HTTP status codes from real traffic that indicate a healthy target."},"successes":{"type":["integer","null"],"minimum":0,"maximum":254,"default":5,"description":"Number of consecutive successful requests to restore a target to healthy status."}}},"unhealthy":{"type":["object","null"],"description":"Thresholds for considering a target unhealthy based on real traffic responses.","properties":{"http_statuses":{"type":["array","null"],"items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[429,500,503],"description":"HTTP status codes from real traffic that indicate an unhealthy target."},"tcp_failures":{"type":["integer","null"],"minimum":0,"maximum":254,"default":2,"description":"Number of TCP failures from real traffic to consider a target unhealthy."},"timeouts":{"type":["integer","null"],"minimum":0,"maximum":254,"default":7,"description":"Number of timeouts from real traffic to consider a target unhealthy."},"http_failures":{"type":["integer","null"],"minimum":0,"maximum":254,"default":5,"description":"Number of HTTP failures from real traffic to consider a target unhealthy."}}}}}}},"tls":{"type":["object","null"],"description":"TLS configuration for connecting to upstream nodes over HTTPS/gRPCS.","properties":{"client_cert_id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"client_cert":{"type":["string","null"],"minLength":128,"maxLength":65536,"description":"PEM-encoded client certificate for mTLS with the upstream."},"client_key":{"type":["string","null"],"minLength":64,"maxLength":65536,"description":"PEM-encoded client private key for mTLS with the upstream."},"verify":{"type":["boolean","null"],"description":"Whether to verify the upstream server certificate. If omitted for HTTPS/gRPCS, follows the NGINX verification setting, which is off unless enabled. Explicit `false` disables verification. For `wss`, explicitly set `true` to enable verification against the shared trust store."},"ca_certs":{"type":["array","null"],"minItems":1,"items":{"type":"string","minLength":128,"maxLength":65536},"description":"PEM-encoded CA certificates for HTTPS/gRPCS upstream verification. Replaces the NGINX trust store for this upstream. If omitted, configure and load the shared store using `proxy_ssl_verify` for HTTPS or `grpc_ssl_verify` for gRPCS. See [Configure Upstream HTTPS](/apisix/how-to-guide/traffic-management/tls-and-mtls/configure-upstream-https). Does not enable verification by itself; set `tls.verify` to `true`. Rejected for `ws` and `wss` upstreams."}}},"keepalive_pool":{"type":["object","null"],"description":"Connection pool configuration for keepalive connections to upstream nodes.","properties":{"size":{"type":["integer","null"],"default":320,"minimum":1,"description":"Maximum number of keepalive connections cached in the connection pool."},"idle_timeout":{"type":["number","null"],"default":60,"minimum":0,"description":"Time in seconds after which an idle keepalive connection is closed. `0` disables the timeout."},"requests":{"type":["integer","null"],"default":1000,"minimum":1,"description":"Maximum number of requests that can be sent over a single keepalive connection before it is closed."}}},"pass_host":{"type":["string","null"],"enum":["pass","node","rewrite",null],"default":"pass","description":"How to set the `Host` header when proxying to the upstream.","x-enumDescriptions":{"pass":"Forward the client's original `Host` header.","node":"Use the upstream node's hostname.","rewrite":"Use the value of `upstream_host`."}},"upstream_host":{"type":["string","null"],"description":"Custom `Host` header value. Only effective when `pass_host` is `rewrite`."},"discovery_type":{"type":["string","null"],"description":"Service discovery type (e.g., `dns`, `consul`, `nacos`, `eureka`). Required when using service discovery instead of static `nodes`."},"discovery_args":{"type":["object","null"],"description":"Additional arguments for service discovery.","properties":{"namespace_id":{"type":["string","null"],"description":"Namespace ID for Nacos service discovery."},"group_name":{"type":["string","null"],"description":"Group name for service discovery."}}},"service_name":{"type":["string","null"],"maxLength":256,"minLength":1,"description":"Service name for service discovery. Required when `discovery_type` is set."}},"additionalProperties":false},"upstream_id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"service_id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"timeout":{"type":["object","null"],"description":"Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.","properties":{"connect":{"type":["number","null"],"exclusiveMinimum":0,"description":"Timeout in seconds for establishing a connection to the upstream.","examples":[6]},"send":{"type":["number","null"],"exclusiveMinimum":0,"description":"Timeout in seconds for sending data to the upstream.","examples":[6]},"read":{"type":["number","null"],"exclusiveMinimum":0,"description":"Timeout in seconds for reading the response from the upstream.","examples":[6]}},"examples":[{"connect":6,"send":6,"read":6}]},"enable_websocket":{"type":["boolean","null"],"description":"Enable WebSocket proxying on this route."},"status":{"type":["integer","null"],"enum":[1,0,null],"default":1,"description":"Route status.","x-enumDescriptions":{"0":"Disabled.","1":"Enabled (default)."}},"script":{"type":["string","null"],"minLength":10,"maxLength":102400,"description":"Lua script for plugin orchestration. Cannot be used together with `plugins` or `plugin_config_id`."},"script_id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]}},"additionalProperties":false},"ServicePatch":{"type":"object","description":"Partial update for an existing `Service`. APISIX recursively merges object fields, replaces arrays, and removes an object field when its value is `null`. The merged resource is then validated against the complete `Service` schema.","properties":{"id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"name":{"type":["string","null"],"maxLength":256,"minLength":1,"description":"Human-readable name."},"desc":{"type":["string","null"],"maxLength":256,"description":"Description of this service."},"labels":{"type":["object","null"],"description":"Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).","additionalProperties":{"type":["string","null"],"pattern":"^\\S+$","maxLength":256,"minLength":1},"examples":[{"env":"production","team":"platform","version":"v2"}]},"create_time":{"type":["integer","null"],"readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":["integer","null"],"readOnly":true,"description":"Unix timestamp of last update. Read-only."},"plugins":{"type":["object","null"],"description":"Plugin configurations as a JSON object. Each key is a plugin name, and the value is that plugin's configuration object.\n\nExample:\n```json\n{\n  \"limit-count\": {\n    \"count\": 100,\n    \"time_window\": 60\n  },\n  \"key-auth\": {}\n}\n```\n\nSee the [Plugin Hub](https://docs.api7.ai/hub) for available plugins and their schemas.","additionalProperties":{"type":["object","null"]},"examples":[{"limit-count":{"count":100,"time_window":60,"rejected_code":429,"key_type":"var","key":"remote_addr"}}]},"upstream":{"type":["object","null"],"description":"Upstream configuration defining backend service nodes and load balancing behavior.\n\nAn upstream must specify either `nodes` (static list) or `service_name` + `discovery_type` (service discovery).","properties":{"id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"name":{"type":["string","null"],"maxLength":256,"minLength":1,"description":"Human-readable name for the upstream."},"desc":{"type":["string","null"],"maxLength":256,"description":"Description of the upstream."},"labels":{"type":["object","null"],"description":"Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).","additionalProperties":{"type":["string","null"],"pattern":"^\\S+$","maxLength":256,"minLength":1},"examples":[{"env":"production","team":"platform","version":"v2"}]},"create_time":{"type":["integer","null"],"description":"Unix timestamp when the upstream was created. Read-only, set automatically.","readOnly":true},"update_time":{"type":["integer","null"],"description":"Unix timestamp when the upstream was last updated. Read-only, set automatically.","readOnly":true},"nodes":{"description":"The upstream endpoints.","anyOf":[{"description":"Upstream backend nodes. Supports two formats:\n\n**Map format** (shorthand): `{\"host:port\": weight}`\n\n**Array format** (full control): `[{\"host\": \"...\", \"port\": ..., \"weight\": ...}]`","anyOf":[{"type":["object","null"],"description":"Upstream nodes as a map of `\"host:port\": weight` pairs. This is the shorthand format.","additionalProperties":{"type":["integer","null"],"minimum":0,"description":"Weight of this node for load balancing. `0` means the node receives no traffic."},"examples":[{"httpbin.org:80":1,"10.0.0.1:8080":2}]},{"type":["array","null"],"items":{"$ref":"#/components/schemas/UpstreamNodeItem"},"title":"Node Objects"},{"type":"null"},{"type":"null"}]},{"type":"null"},{"type":"null"}]},"warm_up_conf":{"type":["object","null"],"description":"Gradually increases the effective weight of newly observed nodes. Only supported for HTTP upstreams using `roundrobin` and a single node priority; ignored by stream routes and rejected in inline `traffic-split` upstreams. The initial node set is already warmed. Each gateway instance tracks ramps independently. This changes traffic distribution, not the total request rate.","properties":{"slow_start_time_seconds":{"type":["integer","null"],"minimum":1,"description":"Seconds for a new node to reach its configured weight."},"min_weight_percent":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Minimum percentage of the configured node weight. Effective positive weights are rounded down but never below 1."},"interval":{"type":["integer","null"],"minimum":1,"default":1,"description":"Seconds between weight refreshes. Cannot exceed `slow_start_time_seconds`."},"aggression":{"type":["number","null"],"minimum":0.01,"default":1,"description":"Ramp shape: 1 is linear, above 1 is faster initially, and below 1 is slower initially."},"startup_grace_period_seconds":{"type":["integer","null"],"minimum":0,"default":0,"description":"Seconds after the gateway starts during which newly observed nodes are treated as already warmed."}},"additionalProperties":false},"retries":{"type":["integer","null"],"minimum":0,"description":"Number of retry attempts when a request to the upstream fails."},"retry_timeout":{"type":["number","null"],"minimum":0,"description":"Maximum time in seconds for retry attempts. `0` disables the retry timeout."},"timeout":{"type":["object","null"],"description":"Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.","properties":{"connect":{"type":["number","null"],"exclusiveMinimum":0,"description":"Timeout in seconds for establishing a connection to the upstream.","examples":[6]},"send":{"type":["number","null"],"exclusiveMinimum":0,"description":"Timeout in seconds for sending data to the upstream.","examples":[6]},"read":{"type":["number","null"],"exclusiveMinimum":0,"description":"Timeout in seconds for reading the response from the upstream.","examples":[6]}},"examples":[{"connect":6,"send":6,"read":6}]},"type":{"type":["string","null"],"default":"roundrobin","enum":["roundrobin","chash","ewma","least_conn",null],"description":"Load balancing algorithm.","x-enumDescriptions":{"roundrobin":"Weighted round-robin distribution (default).","chash":"Consistent hashing for session affinity.","ewma":"Latency-based load balancing using an exponentially weighted moving average.","least_conn":"Least number of active connections."}},"hash_on":{"type":["string","null"],"default":"vars","enum":["vars","header","cookie","consumer","vars_combinations",null],"description":"What to hash on when `type` is `chash`.","x-enumDescriptions":{"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":{"type":["string","null"],"description":"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":{"type":["string","null"],"default":"http","enum":["grpc","grpcs","http","https","ws","wss","tcp","tls","udp","kafka",null],"description":"Protocol for communicating with upstream nodes.","x-enumDescriptions":{"grpc":"Layer 7 gRPC.","grpcs":"Layer 7 gRPC over TLS.","http":"Layer 7 HTTP.","https":"Layer 7 HTTP over TLS.","tcp":"Layer 4 TCP.","tls":"Layer 4 TCP over TLS.","udp":"Layer 4 UDP.","kafka":"Apache Kafka protocol.","ws":"Frame-aware WebSocket proxying; `enable_websocket` is ignored.","wss":"Frame-aware WebSocket proxying over TLS; uses the shared CA trust store, not `tls.ca_certs`."}},"checks":{"type":["object","null"],"description":"Health check configuration for monitoring upstream node availability. Active checks require at least the `active` field.","properties":{"active":{"type":["object","null"],"description":"Active health check configuration. APISIX periodically sends probes to upstream nodes to determine their health status.","properties":{"type":{"type":["string","null"],"enum":["http","https","tcp",null],"default":"http","description":"Protocol type for health check probes."},"timeout":{"type":["number","null"],"default":1,"description":"Timeout in seconds for each health check probe."},"concurrency":{"type":["integer","null"],"default":10,"description":"Number of targets to check concurrently during active health checks."},"host":{"type":["string","null"],"description":"Hostname to use in the health check probe `Host` header. Defaults to the upstream node's host."},"port":{"type":["integer","null"],"minimum":1,"maximum":65535,"description":"Port to use for health check probes. Defaults to the upstream node's port."},"http_path":{"type":["string","null"],"default":"/","description":"HTTP request path for health check probes."},"https_verify_certificate":{"type":["boolean","null"],"default":true,"description":"Whether to verify the upstream's TLS certificate during HTTPS health checks."},"req_headers":{"type":["array","null"],"items":{"type":"string"},"minItems":1,"description":"Additional HTTP headers to include in health check probe requests."},"healthy":{"type":["object","null"],"description":"Thresholds for considering a target healthy during active checks.","properties":{"interval":{"type":["integer","null"],"minimum":1,"default":1,"description":"Interval in seconds between active health check probes for healthy targets."},"http_statuses":{"type":["array","null"],"items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[200,302],"description":"HTTP status codes that indicate a healthy target."},"successes":{"type":["integer","null"],"minimum":1,"maximum":254,"default":2,"description":"Number of consecutive successful probes to consider a target healthy."}}},"unhealthy":{"type":["object","null"],"description":"Thresholds for considering a target unhealthy during active checks.","properties":{"interval":{"type":["integer","null"],"minimum":1,"default":1,"description":"Interval in seconds between active health check probes for unhealthy targets."},"http_statuses":{"type":["array","null"],"items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[429,404,500,501,502,503,504,505],"description":"HTTP status codes that indicate an unhealthy target."},"http_failures":{"type":["integer","null"],"minimum":1,"maximum":254,"default":5,"description":"Number of HTTP failures to consider a target unhealthy."},"tcp_failures":{"type":["integer","null"],"minimum":1,"maximum":254,"default":2,"description":"Number of TCP connection failures to consider a target unhealthy."},"timeouts":{"type":["integer","null"],"minimum":1,"maximum":254,"default":3,"description":"Number of probe timeouts to consider a target unhealthy."}}}}},"passive":{"type":["object","null"],"description":"Passive health check configuration. APISIX monitors real traffic responses to determine upstream node health — no extra probes are sent.","properties":{"type":{"type":["string","null"],"enum":["http","https","tcp",null],"default":"http","description":"Protocol type for passive health monitoring."},"healthy":{"type":["object","null"],"description":"Thresholds for considering a target healthy based on real traffic responses.","properties":{"http_statuses":{"type":["array","null"],"items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[200,201,202,203,204,205,206,207,208,226,300,301,302,303,304,305,306,307,308],"description":"HTTP status codes from real traffic that indicate a healthy target."},"successes":{"type":["integer","null"],"minimum":0,"maximum":254,"default":5,"description":"Number of consecutive successful requests to restore a target to healthy status."}}},"unhealthy":{"type":["object","null"],"description":"Thresholds for considering a target unhealthy based on real traffic responses.","properties":{"http_statuses":{"type":["array","null"],"items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[429,500,503],"description":"HTTP status codes from real traffic that indicate an unhealthy target."},"tcp_failures":{"type":["integer","null"],"minimum":0,"maximum":254,"default":2,"description":"Number of TCP failures from real traffic to consider a target unhealthy."},"timeouts":{"type":["integer","null"],"minimum":0,"maximum":254,"default":7,"description":"Number of timeouts from real traffic to consider a target unhealthy."},"http_failures":{"type":["integer","null"],"minimum":0,"maximum":254,"default":5,"description":"Number of HTTP failures from real traffic to consider a target unhealthy."}}}}}}},"tls":{"type":["object","null"],"description":"TLS configuration for connecting to upstream nodes over HTTPS/gRPCS.","properties":{"client_cert_id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"client_cert":{"type":["string","null"],"minLength":128,"maxLength":65536,"description":"PEM-encoded client certificate for mTLS with the upstream."},"client_key":{"type":["string","null"],"minLength":64,"maxLength":65536,"description":"PEM-encoded client private key for mTLS with the upstream."},"verify":{"type":["boolean","null"],"description":"Whether to verify the upstream server certificate. If omitted for HTTPS/gRPCS, follows the NGINX verification setting, which is off unless enabled. Explicit `false` disables verification. For `wss`, explicitly set `true` to enable verification against the shared trust store."},"ca_certs":{"type":["array","null"],"minItems":1,"items":{"type":"string","minLength":128,"maxLength":65536},"description":"PEM-encoded CA certificates for HTTPS/gRPCS upstream verification. Replaces the NGINX trust store for this upstream. If omitted, configure and load the shared store using `proxy_ssl_verify` for HTTPS or `grpc_ssl_verify` for gRPCS. See [Configure Upstream HTTPS](/apisix/how-to-guide/traffic-management/tls-and-mtls/configure-upstream-https). Does not enable verification by itself; set `tls.verify` to `true`. Rejected for `ws` and `wss` upstreams."}}},"keepalive_pool":{"type":["object","null"],"description":"Connection pool configuration for keepalive connections to upstream nodes.","properties":{"size":{"type":["integer","null"],"default":320,"minimum":1,"description":"Maximum number of keepalive connections cached in the connection pool."},"idle_timeout":{"type":["number","null"],"default":60,"minimum":0,"description":"Time in seconds after which an idle keepalive connection is closed. `0` disables the timeout."},"requests":{"type":["integer","null"],"default":1000,"minimum":1,"description":"Maximum number of requests that can be sent over a single keepalive connection before it is closed."}}},"pass_host":{"type":["string","null"],"enum":["pass","node","rewrite",null],"default":"pass","description":"How to set the `Host` header when proxying to the upstream.","x-enumDescriptions":{"pass":"Forward the client's original `Host` header.","node":"Use the upstream node's hostname.","rewrite":"Use the value of `upstream_host`."}},"upstream_host":{"type":["string","null"],"description":"Custom `Host` header value. Only effective when `pass_host` is `rewrite`."},"discovery_type":{"type":["string","null"],"description":"Service discovery type (e.g., `dns`, `consul`, `nacos`, `eureka`). Required when using service discovery instead of static `nodes`."},"discovery_args":{"type":["object","null"],"description":"Additional arguments for service discovery.","properties":{"namespace_id":{"type":["string","null"],"description":"Namespace ID for Nacos service discovery."},"group_name":{"type":["string","null"],"description":"Group name for service discovery."}}},"service_name":{"type":["string","null"],"maxLength":256,"minLength":1,"description":"Service name for service discovery. Required when `discovery_type` is set."}},"additionalProperties":false},"upstream_id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"script":{"type":["string","null"],"minLength":10,"maxLength":102400,"description":"Lua script for plugin orchestration."},"enable_websocket":{"type":["boolean","null"],"description":"Enable WebSocket proxying for routes using this service."},"hosts":{"type":["array","null"],"items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"Hostnames associated with this service."}},"additionalProperties":false},"UpstreamPatch":{"type":"object","description":"Partial update for an existing `Upstream`. APISIX recursively merges object fields, replaces arrays, and removes an object field when its value is `null`. The merged resource is then validated against the complete `Upstream` schema.","properties":{"id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"name":{"type":["string","null"],"maxLength":256,"minLength":1,"description":"Human-readable name for the upstream."},"desc":{"type":["string","null"],"maxLength":256,"description":"Description of the upstream."},"labels":{"type":["object","null"],"description":"Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).","additionalProperties":{"type":["string","null"],"pattern":"^\\S+$","maxLength":256,"minLength":1},"examples":[{"env":"production","team":"platform","version":"v2"}]},"create_time":{"type":["integer","null"],"description":"Unix timestamp when the upstream was created. Read-only, set automatically.","readOnly":true},"update_time":{"type":["integer","null"],"description":"Unix timestamp when the upstream was last updated. Read-only, set automatically.","readOnly":true},"nodes":{"description":"The upstream endpoints.","anyOf":[{"description":"Upstream backend nodes. Supports two formats:\n\n**Map format** (shorthand): `{\"host:port\": weight}`\n\n**Array format** (full control): `[{\"host\": \"...\", \"port\": ..., \"weight\": ...}]`","anyOf":[{"type":["object","null"],"description":"Upstream nodes as a map of `\"host:port\": weight` pairs. This is the shorthand format.","additionalProperties":{"type":["integer","null"],"minimum":0,"description":"Weight of this node for load balancing. `0` means the node receives no traffic."},"examples":[{"httpbin.org:80":1,"10.0.0.1:8080":2}]},{"type":["array","null"],"items":{"$ref":"#/components/schemas/UpstreamNodeItem"},"title":"Node Objects"},{"type":"null"},{"type":"null"}]},{"type":"null"},{"type":"null"}]},"warm_up_conf":{"type":["object","null"],"description":"Gradually increases the effective weight of newly observed nodes. Only supported for HTTP upstreams using `roundrobin` and a single node priority; ignored by stream routes and rejected in inline `traffic-split` upstreams. The initial node set is already warmed. Each gateway instance tracks ramps independently. This changes traffic distribution, not the total request rate.","properties":{"slow_start_time_seconds":{"type":["integer","null"],"minimum":1,"description":"Seconds for a new node to reach its configured weight."},"min_weight_percent":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Minimum percentage of the configured node weight. Effective positive weights are rounded down but never below 1."},"interval":{"type":["integer","null"],"minimum":1,"default":1,"description":"Seconds between weight refreshes. Cannot exceed `slow_start_time_seconds`."},"aggression":{"type":["number","null"],"minimum":0.01,"default":1,"description":"Ramp shape: 1 is linear, above 1 is faster initially, and below 1 is slower initially."},"startup_grace_period_seconds":{"type":["integer","null"],"minimum":0,"default":0,"description":"Seconds after the gateway starts during which newly observed nodes are treated as already warmed."}},"additionalProperties":false},"retries":{"type":["integer","null"],"minimum":0,"description":"Number of retry attempts when a request to the upstream fails."},"retry_timeout":{"type":["number","null"],"minimum":0,"description":"Maximum time in seconds for retry attempts. `0` disables the retry timeout."},"timeout":{"type":["object","null"],"description":"Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.","properties":{"connect":{"type":["number","null"],"exclusiveMinimum":0,"description":"Timeout in seconds for establishing a connection to the upstream.","examples":[6]},"send":{"type":["number","null"],"exclusiveMinimum":0,"description":"Timeout in seconds for sending data to the upstream.","examples":[6]},"read":{"type":["number","null"],"exclusiveMinimum":0,"description":"Timeout in seconds for reading the response from the upstream.","examples":[6]}},"examples":[{"connect":6,"send":6,"read":6}]},"type":{"type":["string","null"],"default":"roundrobin","enum":["roundrobin","chash","ewma","least_conn",null],"description":"Load balancing algorithm.","x-enumDescriptions":{"roundrobin":"Weighted round-robin distribution (default).","chash":"Consistent hashing for session affinity.","ewma":"Latency-based load balancing using an exponentially weighted moving average.","least_conn":"Least number of active connections."}},"hash_on":{"type":["string","null"],"default":"vars","enum":["vars","header","cookie","consumer","vars_combinations",null],"description":"What to hash on when `type` is `chash`.","x-enumDescriptions":{"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":{"type":["string","null"],"description":"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":{"type":["string","null"],"default":"http","enum":["grpc","grpcs","http","https","ws","wss","tcp","tls","udp","kafka",null],"description":"Protocol for communicating with upstream nodes.","x-enumDescriptions":{"grpc":"Layer 7 gRPC.","grpcs":"Layer 7 gRPC over TLS.","http":"Layer 7 HTTP.","https":"Layer 7 HTTP over TLS.","tcp":"Layer 4 TCP.","tls":"Layer 4 TCP over TLS.","udp":"Layer 4 UDP.","kafka":"Apache Kafka protocol.","ws":"Frame-aware WebSocket proxying; `enable_websocket` is ignored.","wss":"Frame-aware WebSocket proxying over TLS; uses the shared CA trust store, not `tls.ca_certs`."}},"checks":{"type":["object","null"],"description":"Health check configuration for monitoring upstream node availability. Active checks require at least the `active` field.","properties":{"active":{"type":["object","null"],"description":"Active health check configuration. APISIX periodically sends probes to upstream nodes to determine their health status.","properties":{"type":{"type":["string","null"],"enum":["http","https","tcp",null],"default":"http","description":"Protocol type for health check probes."},"timeout":{"type":["number","null"],"default":1,"description":"Timeout in seconds for each health check probe."},"concurrency":{"type":["integer","null"],"default":10,"description":"Number of targets to check concurrently during active health checks."},"host":{"type":["string","null"],"description":"Hostname to use in the health check probe `Host` header. Defaults to the upstream node's host."},"port":{"type":["integer","null"],"minimum":1,"maximum":65535,"description":"Port to use for health check probes. Defaults to the upstream node's port."},"http_path":{"type":["string","null"],"default":"/","description":"HTTP request path for health check probes."},"https_verify_certificate":{"type":["boolean","null"],"default":true,"description":"Whether to verify the upstream's TLS certificate during HTTPS health checks."},"req_headers":{"type":["array","null"],"items":{"type":"string"},"minItems":1,"description":"Additional HTTP headers to include in health check probe requests."},"healthy":{"type":["object","null"],"description":"Thresholds for considering a target healthy during active checks.","properties":{"interval":{"type":["integer","null"],"minimum":1,"default":1,"description":"Interval in seconds between active health check probes for healthy targets."},"http_statuses":{"type":["array","null"],"items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[200,302],"description":"HTTP status codes that indicate a healthy target."},"successes":{"type":["integer","null"],"minimum":1,"maximum":254,"default":2,"description":"Number of consecutive successful probes to consider a target healthy."}}},"unhealthy":{"type":["object","null"],"description":"Thresholds for considering a target unhealthy during active checks.","properties":{"interval":{"type":["integer","null"],"minimum":1,"default":1,"description":"Interval in seconds between active health check probes for unhealthy targets."},"http_statuses":{"type":["array","null"],"items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[429,404,500,501,502,503,504,505],"description":"HTTP status codes that indicate an unhealthy target."},"http_failures":{"type":["integer","null"],"minimum":1,"maximum":254,"default":5,"description":"Number of HTTP failures to consider a target unhealthy."},"tcp_failures":{"type":["integer","null"],"minimum":1,"maximum":254,"default":2,"description":"Number of TCP connection failures to consider a target unhealthy."},"timeouts":{"type":["integer","null"],"minimum":1,"maximum":254,"default":3,"description":"Number of probe timeouts to consider a target unhealthy."}}}}},"passive":{"type":["object","null"],"description":"Passive health check configuration. APISIX monitors real traffic responses to determine upstream node health — no extra probes are sent.","properties":{"type":{"type":["string","null"],"enum":["http","https","tcp",null],"default":"http","description":"Protocol type for passive health monitoring."},"healthy":{"type":["object","null"],"description":"Thresholds for considering a target healthy based on real traffic responses.","properties":{"http_statuses":{"type":["array","null"],"items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[200,201,202,203,204,205,206,207,208,226,300,301,302,303,304,305,306,307,308],"description":"HTTP status codes from real traffic that indicate a healthy target."},"successes":{"type":["integer","null"],"minimum":0,"maximum":254,"default":5,"description":"Number of consecutive successful requests to restore a target to healthy status."}}},"unhealthy":{"type":["object","null"],"description":"Thresholds for considering a target unhealthy based on real traffic responses.","properties":{"http_statuses":{"type":["array","null"],"items":{"type":"integer","minimum":200,"maximum":599},"uniqueItems":true,"default":[429,500,503],"description":"HTTP status codes from real traffic that indicate an unhealthy target."},"tcp_failures":{"type":["integer","null"],"minimum":0,"maximum":254,"default":2,"description":"Number of TCP failures from real traffic to consider a target unhealthy."},"timeouts":{"type":["integer","null"],"minimum":0,"maximum":254,"default":7,"description":"Number of timeouts from real traffic to consider a target unhealthy."},"http_failures":{"type":["integer","null"],"minimum":0,"maximum":254,"default":5,"description":"Number of HTTP failures from real traffic to consider a target unhealthy."}}}}}}},"tls":{"type":["object","null"],"description":"TLS configuration for connecting to upstream nodes over HTTPS/gRPCS.","properties":{"client_cert_id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"client_cert":{"type":["string","null"],"minLength":128,"maxLength":65536,"description":"PEM-encoded client certificate for mTLS with the upstream."},"client_key":{"type":["string","null"],"minLength":64,"maxLength":65536,"description":"PEM-encoded client private key for mTLS with the upstream."},"verify":{"type":["boolean","null"],"description":"Whether to verify the upstream server certificate. If omitted for HTTPS/gRPCS, follows the NGINX verification setting, which is off unless enabled. Explicit `false` disables verification. For `wss`, explicitly set `true` to enable verification against the shared trust store."},"ca_certs":{"type":["array","null"],"minItems":1,"items":{"type":"string","minLength":128,"maxLength":65536},"description":"PEM-encoded CA certificates for HTTPS/gRPCS upstream verification. Replaces the NGINX trust store for this upstream. If omitted, configure and load the shared store using `proxy_ssl_verify` for HTTPS or `grpc_ssl_verify` for gRPCS. See [Configure Upstream HTTPS](/apisix/how-to-guide/traffic-management/tls-and-mtls/configure-upstream-https). Does not enable verification by itself; set `tls.verify` to `true`. Rejected for `ws` and `wss` upstreams."}}},"keepalive_pool":{"type":["object","null"],"description":"Connection pool configuration for keepalive connections to upstream nodes.","properties":{"size":{"type":["integer","null"],"default":320,"minimum":1,"description":"Maximum number of keepalive connections cached in the connection pool."},"idle_timeout":{"type":["number","null"],"default":60,"minimum":0,"description":"Time in seconds after which an idle keepalive connection is closed. `0` disables the timeout."},"requests":{"type":["integer","null"],"default":1000,"minimum":1,"description":"Maximum number of requests that can be sent over a single keepalive connection before it is closed."}}},"pass_host":{"type":["string","null"],"enum":["pass","node","rewrite",null],"default":"pass","description":"How to set the `Host` header when proxying to the upstream.","x-enumDescriptions":{"pass":"Forward the client's original `Host` header.","node":"Use the upstream node's hostname.","rewrite":"Use the value of `upstream_host`."}},"upstream_host":{"type":["string","null"],"description":"Custom `Host` header value. Only effective when `pass_host` is `rewrite`."},"discovery_type":{"type":["string","null"],"description":"Service discovery type (e.g., `dns`, `consul`, `nacos`, `eureka`). Required when using service discovery instead of static `nodes`."},"discovery_args":{"type":["object","null"],"description":"Additional arguments for service discovery.","properties":{"namespace_id":{"type":["string","null"],"description":"Namespace ID for Nacos service discovery."},"group_name":{"type":["string","null"],"description":"Group name for service discovery."}}},"service_name":{"type":["string","null"],"maxLength":256,"minLength":1,"description":"Service name for service discovery. Required when `discovery_type` is set."}},"additionalProperties":false},"GlobalRulePatch":{"type":"object","description":"Partial update for an existing `GlobalRule`. APISIX recursively merges object fields, replaces arrays, and removes an object field when its value is `null`. The merged resource is then validated against the complete `GlobalRule` schema.","properties":{"id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"create_time":{"type":["integer","null"],"readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":["integer","null"],"readOnly":true,"description":"Unix timestamp of last update. Read-only."},"plugins":{"type":["object","null"],"description":"Plugin configurations as a JSON object. Each key is a plugin name, and the value is that plugin's configuration object.\n\nExample:\n```json\n{\n  \"limit-count\": {\n    \"count\": 100,\n    \"time_window\": 60\n  },\n  \"key-auth\": {}\n}\n```\n\nSee the [Plugin Hub](https://docs.api7.ai/hub) for available plugins and their schemas.","additionalProperties":{"type":["object","null"]},"examples":[{"limit-count":{"count":100,"time_window":60,"rejected_code":429,"key_type":"var","key":"remote_addr"}}]}},"additionalProperties":false},"ConsumerGroupPatch":{"type":"object","description":"Partial update for an existing `ConsumerGroup`. APISIX recursively merges object fields, replaces arrays, and removes an object field when its value is `null`. The merged resource is then validated against the complete `ConsumerGroup` schema.","properties":{"id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"name":{"type":["string","null"],"maxLength":256,"minLength":1,"description":"Human-readable name."},"desc":{"type":["string","null"],"maxLength":256,"description":"Description of this group."},"labels":{"type":["object","null"],"description":"Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).","additionalProperties":{"type":["string","null"],"pattern":"^\\S+$","maxLength":256,"minLength":1},"examples":[{"env":"production","team":"platform","version":"v2"}]},"create_time":{"type":["integer","null"],"readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":["integer","null"],"readOnly":true,"description":"Unix timestamp of last update. Read-only."},"plugins":{"type":["object","null"],"description":"Plugin configurations as a JSON object. Each key is a plugin name, and the value is that plugin's configuration object.\n\nExample:\n```json\n{\n  \"limit-count\": {\n    \"count\": 100,\n    \"time_window\": 60\n  },\n  \"key-auth\": {}\n}\n```\n\nSee the [Plugin Hub](https://docs.api7.ai/hub) for available plugins and their schemas.","additionalProperties":{"type":["object","null"]},"examples":[{"limit-count":{"count":100,"time_window":60,"rejected_code":429,"key_type":"var","key":"remote_addr"}}]}},"additionalProperties":false},"PluginConfigPatch":{"type":"object","description":"Partial update for an existing `PluginConfig`. APISIX recursively merges object fields, replaces arrays, and removes an object field when its value is `null`. The merged resource is then validated against the complete `PluginConfig` schema.","properties":{"id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"name":{"type":["string","null"],"description":"Human-readable name."},"desc":{"type":["string","null"],"maxLength":256,"description":"Description."},"labels":{"type":["object","null"],"description":"Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).","additionalProperties":{"type":["string","null"],"pattern":"^\\S+$","maxLength":256,"minLength":1},"examples":[{"env":"production","team":"platform","version":"v2"}]},"create_time":{"type":["integer","null"],"readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":["integer","null"],"readOnly":true,"description":"Unix timestamp of last update. Read-only."},"plugins":{"type":["object","null"],"description":"Plugin configurations as a JSON object. Each key is a plugin name, and the value is that plugin's configuration object.\n\nExample:\n```json\n{\n  \"limit-count\": {\n    \"count\": 100,\n    \"time_window\": 60\n  },\n  \"key-auth\": {}\n}\n```\n\nSee the [Plugin Hub](https://docs.api7.ai/hub) for available plugins and their schemas.","additionalProperties":{"type":["object","null"]},"examples":[{"limit-count":{"count":100,"time_window":60,"rejected_code":429,"key_type":"var","key":"remote_addr"}}]}},"additionalProperties":false},"VaultSecret":{"type":"object","description":"HashiCorp Vault secret-manager configuration.","properties":{"uri":{"type":"string","format":"uri","description":"Vault server URI."},"prefix":{"type":"string","description":"Path prefix for secrets in Vault."},"token":{"type":"string","description":"Vault authentication token or environment-variable URI."},"namespace":{"type":"string","description":"Vault Enterprise or HCP Vault namespace."}},"required":["uri","prefix","token"]},"AwsSecret":{"type":"object","description":"AWS Secrets Manager configuration.","properties":{"access_key_id":{"type":"string","description":"AWS access key ID or environment-variable URI."},"secret_access_key":{"type":"string","description":"AWS secret access key or environment-variable URI."},"session_token":{"type":"string","description":"Optional AWS session token or environment-variable URI."},"region":{"type":"string","default":"us-east-1","description":"AWS region."},"endpoint_url":{"type":"string","format":"uri","description":"Custom AWS Secrets Manager endpoint."}},"required":["access_key_id","secret_access_key"]},"GcpSecret":{"type":"object","description":"Google Cloud Secret Manager configuration.","properties":{"auth_config":{"type":"object","properties":{"client_email":{"type":"string"},"private_key":{"type":"string"},"project_id":{"type":"string"},"token_uri":{"type":"string","default":"https://oauth2.googleapis.com/token"},"scope":{"type":"array","items":{"type":"string"},"default":["https://www.googleapis.com/auth/cloud-platform"]},"entries_uri":{"type":"string","default":"https://secretmanager.googleapis.com/v1"}},"required":["client_email","private_key","project_id"]},"ssl_verify":{"type":"boolean","default":true},"auth_file":{"type":"string","description":"Path to a Google service-account JSON file."}},"oneOf":[{"required":["auth_config"]},{"required":["auth_file"]}]},"Secret":{"description":"Secret-manager configuration. The body must match the manager selected by the `secret_type` path parameter.","anyOf":[{"$ref":"#/components/schemas/VaultSecret"},{"$ref":"#/components/schemas/AwsSecret"},{"$ref":"#/components/schemas/GcpSecret"}]},"SSLPatch":{"type":"object","description":"Partial update for an existing `SSL`. APISIX recursively merges object fields, replaces arrays, and removes an object field when its value is `null`. The merged resource is then validated against the complete `SSL` schema.","properties":{"id":{"description":"Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with `-`, `_`, `.`) or a positive integer.","anyOf":[{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9-_.]+$","examples":["my-route-1"],"title":"String ID"},{"type":["integer","null"],"minimum":1,"examples":[1],"title":"Integer ID"},{"type":"null"}]},"desc":{"type":["string","null"],"maxLength":256,"description":"Description."},"labels":{"type":["object","null"],"description":"Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).","additionalProperties":{"type":["string","null"],"pattern":"^\\S+$","maxLength":256,"minLength":1},"examples":[{"env":"production","team":"platform","version":"v2"}]},"create_time":{"type":["integer","null"],"readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":["integer","null"],"readOnly":true,"description":"Unix timestamp of last update. Read-only."},"type":{"type":["string","null"],"default":"server","enum":["server","client",null],"description":"Certificate type.","x-enumDescriptions":{"server":"HTTPS termination matched by SNI.","client":"Client certificate for mTLS with upstream services."}},"sni":{"type":["string","null"],"description":"Server Name Indication (SNI) to match. Supports wildcard prefix (`*.example.com`). Mutually exclusive with `snis`.","examples":["api.example.com"]},"snis":{"type":["array","null"],"items":{"type":"string"},"minItems":1,"description":"Multiple SNI hostnames. Mutually exclusive with `sni`."},"cert":{"type":["string","null"],"minLength":128,"maxLength":65536,"description":"PEM-encoded server certificate. Can also be a secret reference (`$secret://...`)."},"key":{"type":["string","null"],"minLength":128,"maxLength":65536,"description":"PEM-encoded private key. Can also be a secret reference (`$secret://...`). **Not returned in GET responses for security.**"},"certs":{"type":["array","null"],"items":{"type":"string"},"description":"Additional certificates for certificate chain or alternative key types."},"keys":{"type":["array","null"],"items":{"type":"string"},"description":"Additional private keys corresponding to `certs`."},"client":{"type":["object","null"],"description":"mTLS client verification settings.","properties":{"ca":{"type":["string","null"],"minLength":128,"maxLength":65536,"description":"PEM-encoded CA certificate for client verification."},"depth":{"type":["integer","null"],"minimum":0,"default":1,"description":"Maximum certificate chain depth."},"skip_mtls_uri_regex":{"type":["array","null"],"items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"URI regex patterns to skip mTLS verification."}}},"status":{"type":["integer","null"],"enum":[1,0,null],"default":1,"description":"SSL status.","x-enumDescriptions":{"0":"Disabled.","1":"Enabled (default)."}},"ssl_protocols":{"type":["array","null"],"items":{"type":"string","enum":["TLSv1.1","TLSv1.2","TLSv1.3"]},"maxItems":3,"uniqueItems":true,"description":"Allowed TLS protocol versions."}},"additionalProperties":false},"SecretPatch":{"description":"Partial update for an existing `Secret`. APISIX recursively merges object fields, replaces arrays, and removes an object field when its value is `null`. The merged resource is then validated against the complete `Secret` schema.","anyOf":[{"type":"object","description":"HashiCorp Vault secret-manager configuration.","properties":{"uri":{"type":["string","null"],"format":"uri","description":"Vault server URI."},"prefix":{"type":["string","null"],"description":"Path prefix for secrets in Vault."},"token":{"type":["string","null"],"description":"Vault authentication token or environment-variable URI."},"namespace":{"type":["string","null"],"description":"Vault Enterprise or HCP Vault namespace."}}},{"type":"object","description":"AWS Secrets Manager configuration.","properties":{"access_key_id":{"type":["string","null"],"description":"AWS access key ID or environment-variable URI."},"secret_access_key":{"type":["string","null"],"description":"AWS secret access key or environment-variable URI."},"session_token":{"type":["string","null"],"description":"Optional AWS session token or environment-variable URI."},"region":{"type":["string","null"],"default":"us-east-1","description":"AWS region."},"endpoint_url":{"type":["string","null"],"format":"uri","description":"Custom AWS Secrets Manager endpoint."}}},{"type":"object","description":"Google Cloud Secret Manager configuration.","properties":{"auth_config":{"type":["object","null"],"properties":{"client_email":{"type":["string","null"]},"private_key":{"type":["string","null"]},"project_id":{"type":["string","null"]},"token_uri":{"type":["string","null"],"default":"https://oauth2.googleapis.com/token"},"scope":{"type":["array","null"],"items":{"type":"string"},"default":["https://www.googleapis.com/auth/cloud-platform"]},"entries_uri":{"type":["string","null"],"default":"https://secretmanager.googleapis.com/v1"}}},"ssl_verify":{"type":["boolean","null"],"default":true},"auth_file":{"type":["string","null"],"description":"Path to a Google service-account JSON file."}}}]},"ConfigValidationDocument":{"type":"object","description":"Declarative APISIX configuration to validate. Only the documented resource arrays and their `*_conf_version` fields are evaluated.","properties":{"routes":{"type":"array","description":"Declarative `routes` resources to validate.","items":{"$ref":"#/components/schemas/ConfigValidationRoute"}},"routes_conf_version":{"type":"number","description":"Optional `routes` configuration version. When present, the value must be numeric."},"services":{"type":"array","description":"Declarative `services` resources to validate.","items":{"$ref":"#/components/schemas/ConfigValidationService"}},"services_conf_version":{"type":"number","description":"Optional `services` configuration version. When present, the value must be numeric."},"upstreams":{"type":"array","description":"Declarative `upstreams` resources to validate.","items":{"$ref":"#/components/schemas/ConfigValidationUpstream"}},"upstreams_conf_version":{"type":"number","description":"Optional `upstreams` configuration version. When present, the value must be numeric."},"consumers":{"type":"array","description":"Declarative `consumers` resources to validate.","items":{"oneOf":[{"$ref":"#/components/schemas/ConfigValidationConsumer"},{"$ref":"#/components/schemas/ConfigValidationCredential"}]}},"consumers_conf_version":{"type":"number","description":"Optional `consumers` configuration version. When present, the value must be numeric."},"ssls":{"type":"array","description":"Declarative `ssls` resources to validate.","items":{"$ref":"#/components/schemas/ConfigValidationSSL"}},"ssls_conf_version":{"type":"number","description":"Optional `ssls` configuration version. When present, the value must be numeric."},"global_rules":{"type":"array","description":"Declarative `global_rules` resources to validate.","items":{"$ref":"#/components/schemas/ConfigValidationGlobalRule"}},"global_rules_conf_version":{"type":"number","description":"Optional `global_rules` configuration version. When present, the value must be numeric."},"stream_routes":{"type":"array","description":"Declarative `stream_routes` resources to validate.","items":{"$ref":"#/components/schemas/ConfigValidationStreamRoute"}},"stream_routes_conf_version":{"type":"number","description":"Optional `stream_routes` configuration version. When present, the value must be numeric."},"protos":{"type":"array","description":"Declarative `protos` resources to validate.","items":{"$ref":"#/components/schemas/ConfigValidationProto"}},"protos_conf_version":{"type":"number","description":"Optional `protos` configuration version. When present, the value must be numeric."},"plugin_configs":{"type":"array","description":"Declarative `plugin_configs` resources to validate.","items":{"$ref":"#/components/schemas/ConfigValidationPluginConfig"}},"plugin_configs_conf_version":{"type":"number","description":"Optional `plugin_configs` configuration version. When present, the value must be numeric."},"consumer_groups":{"type":"array","description":"Declarative `consumer_groups` resources to validate.","items":{"$ref":"#/components/schemas/ConfigValidationConsumerGroup"}},"consumer_groups_conf_version":{"type":"number","description":"Optional `consumer_groups` configuration version. When present, the value must be numeric."},"secrets":{"type":"array","description":"Declarative `secrets` resources to validate.","items":{"$ref":"#/components/schemas/Secret"}},"secrets_conf_version":{"type":"number","description":"Optional `secrets` configuration version. When present, the value must be numeric."},"plugin_metadata":{"type":"array","description":"Declarative `plugin_metadata` resources to validate.","items":{"type":"object"}},"plugin_metadata_conf_version":{"type":"number","description":"Optional `plugin_metadata` configuration version. When present, the value must be numeric."},"plugins":{"type":"array","description":"Declarative `plugins` resources to validate.","items":{"type":"object"}},"plugins_conf_version":{"type":"number","description":"Optional `plugins` configuration version. When present, the value must be numeric."}},"additionalProperties":true},"ConfigValidationError":{"type":"object","required":["error"],"properties":{"resource_type":{"type":"string","description":"Top-level resource section that failed validation."},"resource_id":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Resource ID or consumer username, when one is available. An empty string indicates that the invalid item has no ID."},"index":{"type":"integer","minimum":0,"description":"Zero-based index of the invalid resource."},"error":{"type":"string","description":"Validation error for this resource or section."}}},"ConfigValidationErrorResponse":{"type":"object","required":["error_msg","errors"],"properties":{"error_msg":{"type":"string","const":"Configuration validation failed"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ConfigValidationError"}}}},"ConfigValidationCredential":{"type":"object","description":"Credential embedded in the declarative `consumers` array. The ID combines the consumer username and credential ID.\n\nDeclarative credential configuration. The optional `modifiedIndex` controls resource-level change detection with the YAML configuration provider.","properties":{"id":{"type":"string","minLength":15,"maxLength":128,"pattern":"^[a-zA-Z0-9-_]+/credentials/[a-zA-Z0-9-_.]+$","description":"Credential path in the form `consumer/credentials/credential-id`."},"name":{"type":"string","maxLength":256,"minLength":1,"description":"Human-readable name."},"desc":{"type":"string","maxLength":256,"description":"Description of this credential."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"plugins":{"type":"object","maxProperties":1,"description":"Exactly one consumer authentication plugin.","minProperties":1},"modifiedIndex":{"type":"integer","description":"Optional resource version used for change detection by the YAML configuration provider."}},"additionalProperties":false,"required":["id","plugins"]},"ConfigValidationRoute":{"type":"object","description":"Route configuration. A route matches incoming requests by URI, host, methods, and other conditions, then forwards them to an upstream.\n\nA route must have at least a `uri` (or `uris`) and one of: `upstream`, `upstream_id`, `service_id`, or `plugins`.\n\nDeclarative route configuration. The optional `modifiedIndex` controls resource-level change detection with the YAML configuration provider.","properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","maxLength":100,"minLength":1,"description":"Human-readable name for the route."},"desc":{"type":"string","maxLength":256,"description":"Description of what this route does."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"uri":{"type":"string","minLength":1,"maxLength":4096,"description":"URI path pattern to match. Supports exact match (`/api/v1/users`) and prefix match (`/api/*`). Mutually exclusive with `uris`.","examples":["/api/v1/users/*"]},"uris":{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"Multiple URI patterns. Mutually exclusive with `uri`."},"host":{"type":"string","description":"Single hostname to match against the request's `Host` header. Supports wildcard prefix (`*.example.com`). Mutually exclusive with `hosts`.","examples":["api.example.com"]},"hosts":{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"Multiple hostnames to match. Mutually exclusive with `host`."},"methods":{"type":"array","items":{"type":"string","enum":["GET","POST","PUT","DELETE","PATCH","HEAD","OPTIONS","CONNECT","TRACE","PURGE"]},"uniqueItems":true,"description":"HTTP methods allowed on this route. If empty or not set, all methods are allowed.","examples":[["GET","POST"]]},"remote_addr":{"type":"string","description":"Single client IP address or CIDR range to match. Mutually exclusive with `remote_addrs`.","examples":["192.168.1.0/24"]},"remote_addrs":{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"Multiple client IP addresses or CIDR ranges to match. Mutually exclusive with `remote_addr`."},"priority":{"type":"integer","default":0,"description":"Route priority. When multiple routes match the same request, the one with the highest priority wins."},"vars":{"type":"array","description":"Custom matching conditions using [APISIX expressions](https://docs.api7.ai/apisix/reference/router-options). Each condition is an array of `[variable, operator, value]`.","examples":[[["http_user_agent","~*","curl"]]],"items":{}},"filter_func":{"type":"string","minLength":10,"pattern":"^function","description":"Custom Lua function for advanced request matching. Must start with `function`."},"plugins":{"$ref":"#/components/schemas/Plugins"},"plugin_config_id":{"$ref":"#/components/schemas/ResourceId","description":"Reference to a Plugin Config resource. Cannot be used together with `script`."},"upstream":{"$ref":"#/components/schemas/Upstream"},"upstream_id":{"$ref":"#/components/schemas/ResourceId","description":"Reference to an existing Upstream resource."},"service_id":{"$ref":"#/components/schemas/ResourceId","description":"Reference to an existing Service resource."},"timeout":{"$ref":"#/components/schemas/Timeout"},"enable_websocket":{"type":"boolean","description":"Enable WebSocket proxying on this route."},"status":{"type":"integer","enum":[1,0],"default":1,"description":"Route status.","x-enumDescriptions":{"0":"Disabled.","1":"Enabled (default)."}},"script":{"type":"string","minLength":10,"maxLength":102400,"description":"Lua script for plugin orchestration. Cannot be used together with `plugins` or `plugin_config_id`."},"script_id":{"$ref":"#/components/schemas/ResourceId","description":"Script ID (used internally by APISIX Dashboard)."},"modifiedIndex":{"type":"integer","description":"Optional resource version used for change detection by the YAML configuration provider."}},"additionalProperties":false,"anyOf":[{"title":"Plugin and URI required","required":["plugins","uri"]},{"title":"Upstream and URI required","required":["upstream","uri"]},{"title":"Upstream ID and URI required","required":["upstream_id","uri"]},{"title":"Service ID and URI required","required":["service_id","uri"]},{"title":"Plugin and URIs required","required":["plugins","uris"]},{"title":"Upstream and URIs required","required":["upstream","uris"]},{"title":"Upstream ID and URIs required","required":["upstream_id","uris"]},{"title":"Service ID and URIs required","required":["service_id","uris"]},{"title":"Script and URI required","required":["script","uri"]},{"title":"Script and URIs required","required":["script","uris"]}]},"ConfigValidationService":{"type":"object","description":"Service configuration. A service groups an upstream and plugins so multiple routes can share the same backend configuration.\n\nDeclarative service configuration. The optional `modifiedIndex` controls resource-level change detection with the YAML configuration provider.","properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","maxLength":256,"minLength":1,"description":"Human-readable name."},"desc":{"type":"string","maxLength":256,"description":"Description of this service."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"plugins":{"$ref":"#/components/schemas/Plugins"},"upstream":{"$ref":"#/components/schemas/Upstream"},"upstream_id":{"$ref":"#/components/schemas/ResourceId","description":"Reference to an existing Upstream resource."},"script":{"type":"string","minLength":10,"maxLength":102400,"description":"Lua script for plugin orchestration."},"enable_websocket":{"type":"boolean","description":"Enable WebSocket proxying for routes using this service."},"hosts":{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"Hostnames associated with this service."},"modifiedIndex":{"type":"integer","description":"Optional resource version used for change detection by the YAML configuration provider."}},"additionalProperties":false},"ConfigValidationUpstream":{"type":"object","description":"Upstream configuration defining backend service nodes and load balancing behavior.\n\nAn upstream must specify either `nodes` (static list) or `service_name` + `discovery_type` (service discovery).\n\nDeclarative upstream configuration. The optional `modifiedIndex` controls resource-level change detection with the YAML configuration provider.","properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","maxLength":256,"minLength":1,"description":"Human-readable name for the upstream."},"desc":{"type":"string","maxLength":256,"description":"Description of the upstream."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","description":"Unix timestamp when the upstream was created. Read-only, set automatically.","readOnly":true},"update_time":{"type":"integer","description":"Unix timestamp when the upstream was last updated. Read-only, set automatically.","readOnly":true},"nodes":{"description":"The upstream endpoints.","allOf":[{"$ref":"#/components/schemas/UpstreamNodes"}]},"warm_up_conf":{"$ref":"#/components/schemas/UpstreamWarmUp"},"retries":{"type":"integer","minimum":0,"description":"Number of retry attempts when a request to the upstream fails."},"retry_timeout":{"type":"number","minimum":0,"description":"Maximum time in seconds for retry attempts. `0` disables the retry timeout."},"timeout":{"$ref":"#/components/schemas/Timeout"},"type":{"type":"string","default":"roundrobin","enum":["roundrobin","chash","ewma","least_conn"],"description":"Load balancing algorithm.","x-enumDescriptions":{"roundrobin":"Weighted round-robin distribution (default).","chash":"Consistent hashing for session affinity.","ewma":"Latency-based load balancing using an exponentially weighted moving average.","least_conn":"Least number of active connections."}},"hash_on":{"type":"string","default":"vars","enum":["vars","header","cookie","consumer","vars_combinations"],"description":"What to hash on when `type` is `chash`.","x-enumDescriptions":{"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":{"type":"string","description":"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":{"type":"string","default":"http","enum":["grpc","grpcs","http","https","ws","wss","tcp","tls","udp","kafka"],"description":"Protocol for communicating with upstream nodes.","x-enumDescriptions":{"grpc":"Layer 7 gRPC.","grpcs":"Layer 7 gRPC over TLS.","http":"Layer 7 HTTP.","https":"Layer 7 HTTP over TLS.","tcp":"Layer 4 TCP.","tls":"Layer 4 TCP over TLS.","udp":"Layer 4 UDP.","kafka":"Apache Kafka protocol.","ws":"Frame-aware WebSocket proxying; `enable_websocket` is ignored.","wss":"Frame-aware WebSocket proxying over TLS; uses the shared CA trust store, not `tls.ca_certs`."}},"checks":{"$ref":"#/components/schemas/HealthCheck"},"tls":{"$ref":"#/components/schemas/UpstreamTLS"},"keepalive_pool":{"$ref":"#/components/schemas/KeepalivePool"},"pass_host":{"type":"string","enum":["pass","node","rewrite"],"default":"pass","description":"How to set the `Host` header when proxying to the upstream.","x-enumDescriptions":{"pass":"Forward the client's original `Host` header.","node":"Use the upstream node's hostname.","rewrite":"Use the value of `upstream_host`."}},"upstream_host":{"type":"string","description":"Custom `Host` header value. Only effective when `pass_host` is `rewrite`."},"discovery_type":{"type":"string","description":"Service discovery type (e.g., `dns`, `consul`, `nacos`, `eureka`). Required when using service discovery instead of static `nodes`."},"discovery_args":{"type":"object","description":"Additional arguments for service discovery.","properties":{"namespace_id":{"type":"string","description":"Namespace ID for Nacos service discovery."},"group_name":{"type":"string","description":"Group name for service discovery."}}},"service_name":{"type":"string","maxLength":256,"minLength":1,"description":"Service name for service discovery. Required when `discovery_type` is set."},"modifiedIndex":{"type":"integer","description":"Optional resource version used for change detection by the YAML configuration provider."}},"oneOf":[{"required":["nodes"],"title":"Use Upstream Nodes"},{"required":["service_name","discovery_type"],"title":"Use Service Registry"}],"additionalProperties":false},"ConfigValidationConsumer":{"type":"object","description":"Consumer configuration. Represents an API user or application with authentication credentials and plugin policies.\n\nDeclarative consumer configuration. The optional `modifiedIndex` controls resource-level change detection with the YAML configuration provider.","required":["username"],"properties":{"username":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[a-zA-Z0-9_\\-]+$","description":"Unique username for the consumer. Only alphanumeric characters, hyphens, and underscores are allowed.","examples":["my-app"]},"desc":{"type":"string","maxLength":256,"description":"Description of this consumer."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"group_id":{"$ref":"#/components/schemas/ResourceId","description":"Reference to a Consumer Group for shared plugin configurations."},"plugins":{"$ref":"#/components/schemas/Plugins"},"modifiedIndex":{"type":"integer","description":"Optional resource version used for change detection by the YAML configuration provider."}},"additionalProperties":false},"ConfigValidationSSL":{"type":"object","description":"SSL certificate configuration for TLS termination or mTLS.\n\nDeclarative SSL resource configuration. The optional `modifiedIndex` controls resource-level change detection with the YAML configuration provider.","properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"desc":{"type":"string","maxLength":256,"description":"Description."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"type":{"type":"string","default":"server","enum":["server","client"],"description":"Certificate type.","x-enumDescriptions":{"server":"HTTPS termination matched by SNI.","client":"Client certificate for mTLS with upstream services."}},"sni":{"type":"string","description":"Server Name Indication (SNI) to match. Supports wildcard prefix (`*.example.com`). Mutually exclusive with `snis`.","examples":["api.example.com"]},"snis":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Multiple SNI hostnames. Mutually exclusive with `sni`."},"cert":{"type":"string","minLength":128,"maxLength":65536,"description":"PEM-encoded server certificate. Can also be a secret reference (`$secret://...`)."},"key":{"type":"string","minLength":128,"maxLength":65536,"description":"PEM-encoded private key. Can also be a secret reference (`$secret://...`). **Not returned in GET responses for security.**"},"certs":{"type":"array","items":{"type":"string"},"description":"Additional certificates for certificate chain or alternative key types."},"keys":{"type":"array","items":{"type":"string"},"description":"Additional private keys corresponding to `certs`."},"client":{"type":"object","description":"mTLS client verification settings.","required":["ca"],"properties":{"ca":{"type":"string","minLength":128,"maxLength":65536,"description":"PEM-encoded CA certificate for client verification."},"depth":{"type":"integer","minimum":0,"default":1,"description":"Maximum certificate chain depth."},"skip_mtls_uri_regex":{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true,"description":"URI regex patterns to skip mTLS verification."}}},"status":{"type":"integer","enum":[1,0],"default":1,"description":"SSL status.","x-enumDescriptions":{"0":"Disabled.","1":"Enabled (default)."}},"ssl_protocols":{"type":"array","items":{"type":"string","enum":["TLSv1.1","TLSv1.2","TLSv1.3"]},"maxItems":3,"uniqueItems":true,"description":"Allowed TLS protocol versions."},"modifiedIndex":{"type":"integer","description":"Optional resource version used for change detection by the YAML configuration provider."}},"additionalProperties":false,"if":{"properties":{"type":{"enum":["server"]}}},"then":{"oneOf":[{"title":"Single SNI","required":["sni","key","cert"]},{"title":"Multiple SNIs","required":["snis","key","cert"]}]},"else":{"title":"SNI not required"}},"ConfigValidationStreamRoute":{"type":"object","description":"Stream Route for TCP/UDP (L4) proxying. Matches transport-layer connections by client IP, server address/port, or SNI.\n\nDeclarative stream route configuration. The optional `modifiedIndex` controls resource-level change detection with the YAML configuration provider.","properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","maxLength":256,"minLength":1,"description":"Human-readable name."},"desc":{"type":"string","maxLength":256,"description":"Description."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"remote_addr":{"type":"string","description":"Client IP address or CIDR range to match."},"server_addr":{"type":"string","description":"Server IP address to match."},"server_port":{"type":"integer","minimum":1,"maximum":65535,"description":"Server port to match."},"sni":{"type":"string","description":"SNI hostname to match. Supports wildcard hostnames. Mutually exclusive with `snis`.","pattern":"^\\*$|^\\*?[0-9a-zA-Z-._\\[\\]:]+$"},"upstream":{"$ref":"#/components/schemas/Upstream"},"upstream_id":{"$ref":"#/components/schemas/ResourceId","description":"Reference to an existing Upstream."},"service_id":{"$ref":"#/components/schemas/ResourceId","description":"Reference to an existing Service."},"plugins":{"$ref":"#/components/schemas/Plugins"},"modifiedIndex":{"type":"integer","description":"Optional resource version used for change detection by the YAML configuration provider."},"snis":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","pattern":"^\\*$|^\\*?[0-9a-zA-Z-._\\[\\]:]+$"},"description":"Alternative SNI hostnames to match, including wildcard hostnames. Mutually exclusive with `sni`."},"tls_passthrough":{"type":"boolean","default":false,"description":"On a listener configured with both `tls` and `tls_passthrough`, `true` forwards encrypted TLS bytes to the upstream; `false` terminates TLS at APISIX. Ignored on dedicated listeners. Passthrough requires a TCP upstream, not scheme `tls`."}},"additionalProperties":false,"not":{"required":["sni","snis"]}},"ConfigValidationPluginConfig":{"type":"object","description":"Plugin Config — a reusable set of plugin configurations that can be referenced by multiple routes.\n\nDeclarative plugin config configuration. The optional `modifiedIndex` controls resource-level change detection with the YAML configuration provider.","required":["plugins"],"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","description":"Human-readable name."},"desc":{"type":"string","maxLength":256,"description":"Description."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"plugins":{"$ref":"#/components/schemas/Plugins"},"modifiedIndex":{"type":"integer","description":"Optional resource version used for change detection by the YAML configuration provider."}},"additionalProperties":false},"ConfigValidationConsumerGroup":{"type":"object","description":"Consumer Group configuration. Defines shared plugin configurations for multiple consumers.\n\nDeclarative consumer group configuration. The optional `modifiedIndex` controls resource-level change detection with the YAML configuration provider.","required":["plugins"],"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","maxLength":256,"minLength":1,"description":"Human-readable name."},"desc":{"type":"string","maxLength":256,"description":"Description of this group."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"plugins":{"$ref":"#/components/schemas/Plugins"},"modifiedIndex":{"type":"integer","description":"Optional resource version used for change detection by the YAML configuration provider."}},"additionalProperties":false},"ConfigValidationGlobalRule":{"type":"object","description":"Global Rule configuration. Global plugins apply independently of locally bound plugins. For HTTP requests, execution is interleaved by phase: global `rewrite`, local `rewrite`, global `access`, then local `access`. Priorities order plugins within each phase and scope, and an early response skips handlers scheduled later.\n\nDeclarative global rule configuration. The optional `modifiedIndex` controls resource-level change detection with the YAML configuration provider.","required":["plugins"],"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"plugins":{"$ref":"#/components/schemas/Plugins"},"modifiedIndex":{"type":"integer","description":"Optional resource version used for change detection by the YAML configuration provider."}},"additionalProperties":false},"ConfigValidationProto":{"type":"object","description":"Protocol buffer definition for gRPC transcoding.\n\nDeclarative proto configuration. The optional `modifiedIndex` controls resource-level change detection with the YAML configuration provider.","required":["content"],"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","maxLength":256,"minLength":1,"description":"Human-readable name."},"desc":{"type":"string","maxLength":256,"description":"Description."},"labels":{"$ref":"#/components/schemas/Labels"},"create_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of creation. Read-only."},"update_time":{"type":"integer","readOnly":true,"description":"Unix timestamp of last update. Read-only."},"content":{"type":"string","minLength":1,"maxLength":1048576,"description":"Protobuf `.proto` file content as a string."},"modifiedIndex":{"type":"integer","description":"Optional resource version used for change detection by the YAML configuration provider."}},"additionalProperties":false},"UpstreamWarmUp":{"type":"object","description":"Gradually increases the effective weight of newly observed nodes. Only supported for HTTP upstreams using `roundrobin` and a single node priority; ignored by stream routes and rejected in inline `traffic-split` upstreams. The initial node set is already warmed. Each gateway instance tracks ramps independently. This changes traffic distribution, not the total request rate.","properties":{"slow_start_time_seconds":{"type":"integer","minimum":1,"description":"Seconds for a new node to reach its configured weight."},"min_weight_percent":{"type":"integer","minimum":1,"maximum":100,"description":"Minimum percentage of the configured node weight. Effective positive weights are rounded down but never below 1."},"interval":{"type":"integer","minimum":1,"default":1,"description":"Seconds between weight refreshes. Cannot exceed `slow_start_time_seconds`."},"aggression":{"type":"number","minimum":0.01,"default":1,"description":"Ramp shape: 1 is linear, above 1 is faster initially, and below 1 is slower initially."},"startup_grace_period_seconds":{"type":"integer","minimum":0,"default":0,"description":"Seconds after the gateway starts during which newly observed nodes are treated as already warmed."}},"required":["slow_start_time_seconds","min_weight_percent"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"**Bad Request** — The request body is invalid or missing required fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"validation_error":{"summary":"Schema validation error","value":{"error_msg":"invalid configuration: property \"uri\" is required"}},"invalid_json":{"summary":"Malformed JSON body","value":{"error_msg":"invalid request body: unexpected character at line 1 column 2"}}}}}},"Unauthorized":{"description":"**Unauthorized** — The API key is missing, invalid, or lacks permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"missing_key":{"summary":"No API key provided","value":{"error_msg":"failed to check token","description":"missing apikey"}},"wrong_key":{"summary":"Invalid API key","value":{"error_msg":"failed to check token","description":"wrong apikey"}},"viewer_role":{"summary":"Viewer role attempting write operation","value":{"error_msg":"failed to check token","description":"invalid method for role viewer"}}}}}},"NotFound":{"description":"**Not Found** — The specified resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"},"example":{"error_msg":"Key not found"}}}}},"parameters":{"Ttl":{"name":"ttl","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Time-to-live in seconds. The resource is automatically removed when it expires.","example":3600},"Force":{"name":"force","in":"query","required":false,"schema":{"type":"string","enum":["true"]},"description":"When `true`, skip dependency checks before deletion.","example":"true"},"Page":{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number (1-based).","example":1},"PageSize":{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":10,"maximum":500},"description":"Items per page (10–500). When omitted, no pagination is applied and the full list is returned.","example":20},"IdInPath":{"name":"id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"},"description":"Resource identifier.","example":"r1"},"SecretType":{"name":"secret_type","in":"path","required":true,"schema":{"type":"string","enum":["vault","aws","gcp"]},"description":"Secret manager backend.","example":"vault"},"NameFilter":{"name":"name","in":"query","required":false,"schema":{"type":"string"},"description":"Filter list by `name` (regex match)."},"LabelFilter":{"name":"label","in":"query","required":false,"schema":{"type":"string"},"description":"Filter list to resources with the given label key.","example":"env"},"UriFilter":{"name":"uri","in":"query","required":false,"schema":{"type":"string"},"description":"Filter routes by URI (regex match against `uri` or any `uris[]`)."},"FilterExpr":{"name":"filter","in":"query","required":false,"schema":{"type":"string"},"description":"Filter expression. Supports `service_id` and `upstream_id`. URL-encoded query string, e.g. `service_id%3D1`."},"UsernameInPath":{"name":"username","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[a-zA-Z0-9_\\-]+$"},"description":"Consumer username.","example":"jack"},"PluginNameInPath":{"name":"plugin_name","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Plugin name.","example":"limit-count"},"Subsystem":{"name":"subsystem","in":"query","required":false,"schema":{"type":"string","enum":["http","stream"],"default":"http"},"description":"Plugin subsystem."},"PluginListAll":{"name":"all","in":"query","required":true,"schema":{"type":"string","enum":["true"]},"description":"Deprecated. When `true`, return the full plugin catalog.","deprecated":true},"ResourceKindInPath":{"name":"resource","in":"path","required":true,"schema":{"type":"string","enum":["routes","services","upstreams","consumers","ssls","plugin_configs","global_rules","stream_routes","protos","consumer_groups","credentials"]},"description":"Resource kind.","example":"routes"}},"requestBodies":{"GraphQLCostDecorationPatchBody":{"description":"Fields to merge into an existing GraphQL cost decoration. The owning service cannot be changed. The merged resource must pass validation.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphQLCostDecorationPatch"},"examples":{"changeMultiplier":{"summary":"Change the descendant cost multiplier","value":{"mul_value":2}},"usePaginationArgument":{"summary":"Multiply descendant cost by a pagination argument","value":{"mul_arguments":["first"]}}}}}},"CredentialUpsert":{"description":"`Credential` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credential"},"example":{"plugins":{"key-auth":{"key":"credential-secret-key-456"}}}}}},"PluginMetadataUpsert":{"description":"Plugin metadata. The body schema is plugin-specific (the plugin's `metadata_schema`). Fetch via `GET /apisix/admin/schema/plugins/{plugin_name}`.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"RouteUpsertPostCollection":{"description":"`Route` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Route"},"example":{"name":"my-api-route","desc":"Route for user management API","uri":"/api/v1/users/*","hosts":["api.example.com"],"methods":["GET","POST","PUT","DELETE"],"plugins":{"limit-count":{"count":100,"time_window":60,"rejected_code":429,"key_type":"var","key":"remote_addr"}},"upstream":{"type":"roundrobin","nodes":{"10.0.0.1:8080":3,"10.0.0.2:8080":2},"retries":2,"timeout":{"connect":6,"send":6,"read":6}}}}}},"RouteUpsertPutId":{"description":"`Route` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Route"},"example":{"name":"payments-route","desc":"Route for payment processing API","uri":"/api/v1/payments","methods":["POST"],"plugins":{"key-auth":{},"limit-count":{"count":10,"time_window":60,"rejected_code":429,"key_type":"var","key":"consumer_name"}},"upstream":{"type":"roundrobin","nodes":{"payments-service:8080":1}},"timeout":{"connect":10,"send":10,"read":30}}}}},"RouteUpsertPatchId":{"description":"Fields to merge into the existing `Route`. Object fields are merged recursively; arrays are replaced.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoutePatch"},"examples":{"disableRoute":{"summary":"Disable the route","value":{"status":0}},"addUpstreamNode":{"summary":"Add an upstream node","value":{"upstream":{"nodes":{"127.0.0.1:1981":1}}}},"deleteUpstreamNode":{"summary":"Delete an upstream node","value":{"upstream":{"nodes":{"127.0.0.1:1980":null}}}},"replaceMethods":{"summary":"Replace the allowed methods","value":{"methods":["GET","POST"]}}}}}},"ServiceUpsertPostCollection":{"description":"`Service` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"},"example":{"plugins":{},"upstream":{"type":"roundrobin","nodes":{"127.0.0.1:1980":1}},"name":"service-test","desc":"hello world","enable_websocket":true,"hosts":["foo.com"]}}}},"ServiceUpsertPutId":{"description":"`Service` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"},"example":{"name":"user-service","desc":"User management microservice","upstream":{"type":"roundrobin","nodes":{"user-svc:8080":1}},"plugins":{"limit-count":{"count":200,"time_window":60,"rejected_code":429,"key_type":"var","key":"remote_addr"}}}}}},"ServiceUpsertPatchId":{"description":"Fields to merge into the existing `Service`. Object fields are merged recursively; arrays are replaced.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServicePatch"},"examples":{"updateDescription":{"summary":"Update the service description","value":{"desc":"Updated service description"}},"addUpstreamNode":{"summary":"Add an inline upstream node","value":{"upstream":{"nodes":{"127.0.0.1:1981":1}}}}}}}},"UpstreamUpsertPostCollection":{"description":"`Upstream` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Upstream"},"example":{"name":"upstream-for-test","desc":"desc","scheme":"http","retries":1,"type":"roundrobin","nodes":{"127.0.0.1:1980":1},"timeout":{"connect":15,"send":15,"read":15}}}}},"UpstreamUpsertPutId":{"description":"`Upstream` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Upstream"},"example":{"name":"backend-cluster","desc":"Primary backend service cluster","type":"roundrobin","nodes":{"10.0.0.1:8080":3,"10.0.0.2:8080":2,"10.0.0.3:8080":1},"retries":3,"retry_timeout":5,"timeout":{"connect":6,"send":6,"read":6},"checks":{"active":{"type":"http","http_path":"/health","healthy":{"interval":5,"successes":2},"unhealthy":{"interval":3,"http_failures":3,"tcp_failures":2}}},"scheme":"http","pass_host":"pass"}}}},"UpstreamUpsertPatchId":{"description":"Fields to merge into the existing `Upstream`. Object fields are merged recursively; arrays are replaced.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpstreamPatch"},"examples":{"updateDescription":{"summary":"Update the upstream description","value":{"desc":"Updated upstream description"}},"addNode":{"summary":"Add an upstream node","value":{"nodes":{"127.0.0.1:1981":1}}}}}}},"ConsumerUpsertPutCollection":{"description":"`Consumer` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Consumer"},"example":{"username":"my-app","desc":"Mobile application consumer","labels":{"team":"mobile","env":"production"},"plugins":{"key-auth":{"key":"app-secret-key-123"}}}}}},"ConsumerGroupUpsertPutId":{"description":"`ConsumerGroup` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerGroup"},"example":{"plugins":{"limit-count":{"count":200,"time_window":60,"rejected_code":429,"key_type":"var","key":"consumer_name"}}}}}},"ConsumerGroupUpsertPatchId":{"description":"Fields to merge into the existing `ConsumerGroup`. Object fields are merged recursively; arrays are replaced.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerGroupPatch"},"examples":{"updateDescription":{"summary":"Update the consumer group description","value":{"desc":"Updated consumer group description"}},"configurePlugin":{"summary":"Configure a plugin","value":{"plugins":{"limit-count":{"count":100,"time_window":60,"rejected_code":429}}}}}}}},"SslUpsertPostCollection":{"description":"`SSL` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SSL"},"example":{"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"}}}},"SslUpsertPutId":{"description":"`SSL` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SSL"},"example":{"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"}}}},"GlobalRuleUpsertPutId":{"description":"`GlobalRule` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalRule"},"example":{"plugins":{"prometheus":{},"ip-restriction":{"whitelist":["10.0.0.0/8","172.16.0.0/12"]}}}}}},"GlobalRuleUpsertPatchId":{"description":"Fields to merge into the existing `GlobalRule`. Object fields are merged recursively; arrays are replaced.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalRulePatch"},"examples":{"enablePlugin":{"summary":"Enable a plugin","value":{"plugins":{"serverless-pre-function":{"phase":"rewrite","functions":["return function() end"]}}}},"removePlugin":{"summary":"Remove a plugin","value":{"plugins":{"serverless-pre-function":null}}}}}}},"PluginConfigUpsertPutId":{"description":"`PluginConfig` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginConfig"},"example":{"plugins":{"limit-count":{"count":100,"time_window":60,"rejected_code":429,"key_type":"var","key":"remote_addr"},"proxy-rewrite":{"uri":"/backend$uri"}}}}}},"PluginConfigUpsertPatchId":{"description":"Fields to merge into the existing `PluginConfig`. Object fields are merged recursively; arrays are replaced.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginConfigPatch"},"examples":{"updateDescription":{"summary":"Update the plugin config description","value":{"desc":"Updated plugin config description"}},"configurePlugin":{"summary":"Configure a plugin","value":{"plugins":{"limit-count":{"count":100,"time_window":60,"rejected_code":429}}}}}}}},"StreamRouteUpsertPostCollection":{"description":"`StreamRoute` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StreamRoute"},"example":{"server_addr":"127.0.0.1","server_port":2000,"upstream":{"nodes":{"127.0.0.1:1995":1},"type":"roundrobin"}}}}},"StreamRouteUpsertPutId":{"description":"`StreamRoute` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StreamRoute"},"example":{"server_addr":"127.0.0.1","server_port":2000,"upstream":{"nodes":{"127.0.0.1:1995":1},"type":"roundrobin"}}}}},"ProtoUpsertPostCollection":{"description":"`Proto` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proto"},"example":{"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}"}}}},"ProtoUpsertPutId":{"description":"`Proto` configuration body for create / replace / patch.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proto"},"example":{"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}"}}}},"SecretUpsertPutCollection":{"description":"Complete secret-manager configuration for the manager selected by `secret_type`.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Secret"},"examples":{"vault":{"summary":"HashiCorp Vault","value":{"uri":"https://vault.example.com","prefix":"apisix","token":"$ENV://VAULT_TOKEN","namespace":"team-a"}},"aws":{"summary":"AWS Secrets Manager","value":{"access_key_id":"$ENV://AWS_ACCESS_KEY_ID","secret_access_key":"$ENV://AWS_SECRET_ACCESS_KEY","region":"us-east-1"}},"gcp":{"summary":"Google Cloud Secret Manager","value":{"auth_file":"/etc/apisix/gcp-service-account.json","ssl_verify":true}}}}}},"SecretUpsertPatchCollection":{"description":"Fields to merge into the existing secret-manager configuration.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecretPatch"},"examples":{"vaultToken":{"summary":"Update a Vault token","value":{"token":"$ENV://VAULT_TOKEN"}},"awsRegion":{"summary":"Update an AWS region","value":{"region":"eu-west-1"}},"gcpTls":{"summary":"Disable GCP endpoint verification","value":{"ssl_verify":false}}}}}},"SslUpsertPatchId":{"description":"Fields to merge into the existing `SSL`. Object fields are merged recursively; arrays are replaced.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SSLPatch"},"examples":{"updateSnis":{"summary":"Replace the SNI hostnames","value":{"snis":["api.example.com","admin.example.com"]}},"disableCertificate":{"summary":"Disable the certificate","value":{"status":0}}}}}}}},"security":[{"adminKey":[]},{"apiKeyQuery":[]},{"apiKeyCookie":[]}]}