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. APISIX Admin API allows you to dynamically configure the API gateway without restarts. All changes take effect immediately. All endpoints require an **API key** passed via the `X-API-KEY` request header. The API key is configured in APISIX's `config.yaml` under `deployment.admin.admin_key`. The default Admin API listens on `http://127.0.0.1:9180`. You can customize the host and port in `config.yaml` under `deployment.admin.admin_listen`. See [APISIX Documentation](https://docs.api7.ai/apisix/getting-started/) for more information. version: 3.17.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. A route must include at least a **URI pattern** and one of: an inline `upstream`, an `upstream_id`, a `service_id`, or `plugins`. **Key Features** - Match by URI, host, HTTP method, headers, query parameters, and custom expressions - Attach plugins for authentication, rate limiting, transformation, and more - Support WebSocket proxying and gRPC transcoding - Priority-based routing when multiple routes match See [Routes documentation](https://docs.api7.ai/apisix/key-concepts/routes) for more. 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. **Load Balancing Algorithms** - `roundrobin` — Weighted round-robin (default) - `chash` — Consistent hashing for session affinity - `ewma` — Latency-based selection (exponentially weighted moving average) - `least_conn` — Fewest active connections **Health Checks** Upstreams support **active** and **passive** health checks to automatically remove unhealthy nodes from the load balancing pool. See [Upstreams documentation](https://docs.api7.ai/apisix/key-concepts/upstreams) for more. 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. When a route references a service via `service_id`, the service's upstream and plugins are merged with the route's own configuration. Route-level settings take precedence. See [Services documentation](https://docs.api7.ai/apisix/key-concepts/services) for more. 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. Each consumer is uniquely identified by a `username` and can belong to a consumer group. See [Consumers documentation](https://docs.api7.ai/apisix/key-concepts/consumers) for more. 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. Consumers reference a group via the `group_id` field. Group-level plugins are merged with consumer-level plugins, with consumer-level taking precedence. See [Consumer Groups documentation](https://docs.api7.ai/apisix/key-concepts/consumer-groups) for more. 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`). Credentials are sub-resources of consumers. A consumer can have multiple credentials, each for a different authentication method. See [Credentials documentation](https://docs.api7.ai/apisix/key-concepts/credentials) for more. 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. Use these endpoints to query available plugins and their JSON schemas, or to hot-reload plugins without restarting APISIX. Plugins are attached to routes, services, consumers, or global rules via the `plugins` object. See [Plugin Hub](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`. Route-level plugins are merged with plugin config plugins, with route-level taking precedence. See [Plugin Configs documentation](https://docs.api7.ai/apisix/key-concepts/plugin-configs) for more. 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. For example, setting metadata for `http-logger` will affect every route that uses `http-logger`. See [Plugin Metadata documentation](https://docs.api7.ai/apisix/key-concepts/plugin-metadata) for more. x-displayName: Plugin Metadata - name: Global Rules description: >- A **Global Rule** defines plugins that are executed on **every** incoming request, before any route-specific plugins run. Use global rules for cross-cutting concerns like IP allowlists, request logging, or metrics collection. Global rules are evaluated in order of their `id`. Plugin execution order within a global rule follows standard APISIX plugin priority. See [Global Rules documentation](https://docs.api7.ai/apisix/key-concepts/plugin-global-rules) for more. 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. Stream routes match traffic by `remote_addr`, `server_addr`, `server_port`, or `sni` (for TLS connections). **Note:** Stream mode must be enabled in `config.yaml` (`apisix.proxy_mode: stream` or `http&stream`) before creating stream routes. See [Stream Routes documentation](https://docs.api7.ai/apisix/key-concepts/stream-routes) for more. x-displayName: Stream Routes - name: SSL Certificates description: >- The **SSL** resource manages TLS certificates for HTTPS termination and mTLS authentication. **Certificate Types** - `server` — Server certificate for HTTPS termination (matched by SNI) - `client` — Client certificate for mTLS with upstream services APISIX dynamically selects the correct certificate based on the SNI (Server Name Indication) in the TLS handshake. Certificates can be rotated without restart. See [SSL documentation](https://docs.api7.ai/apisix/key-concepts/ssl-certificates) for more. 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. Once configured, you can reference secrets in plugin configurations using the URI format: `$secret://vault/my-secret/key`. See [Secrets documentation](https://docs.api7.ai/apisix/key-concepts/secrets) for more. 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. Upload your `.proto` definitions here, then reference them by ID in the `grpc-transcode` plugin configuration. See [gRPC Transcode plugin](https://docs.api7.ai/hub/grpc-transcode) for more. x-displayName: Protos - name: Schema Validation description: >- The **Schema Validation** endpoint lets you validate a resource configuration against APISIX's JSON Schema without actually creating the resource. Use this for dry-run validation in CI/CD pipelines or configuration management tools. x-displayName: Schema Validation - name: Health description: Liveness probe. - name: Standalone description: >- Endpoints exposed when the deployment uses the YAML config provider (`deployment.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. Results 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 \ -H 'X-API-KEY: your-api-key' post: summary: Create a Route description: >- Create a new route with an auto-generated ID. A route must include at least a `uri` and one of: `upstream` (inline), `upstream_id`, `service_id`, or `plugins`. 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 \ -H 'X-API-KEY: your-api-key' \ -H 'Content-Type: application/json' \ -X POST -d '{ "uri": "/api/v1/users/*", "upstream": { "type": "roundrobin", "nodes": {"10.0.0.1:8080": 1} } }' /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. **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 \ -H 'X-API-KEY: your-api-key' \ -H 'Content-Type: application/json' \ -X PUT -d '{ "uri": "/api/v1/payments", "methods": ["POST"], "upstream": { "type": "roundrobin", "nodes": {"payments-service:8080": 1} } }' 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 \ -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. **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 \ -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/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 \ -H 'X-API-KEY: your-api-key' \ -H 'Content-Type: application/json' \ -X PUT -d '{ "username": "my-app", "plugins": { "key-auth": {"key": "app-secret-key-123"} } }' 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----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDh5cAWYXAMPLEbe fakekeyForOpenAPISpecPlaceholderOnlyDoNotUseForRealKeysNopeNopeNo peNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNo peNopeNopeNopeNopeNopeNope== -----END PRIVATE KEY----- snis: - test.com id: '1' create_time: 1684373523 status: 1 cert: > -----BEGIN CERTIFICATE----- MIIDazCCAlOgAwIBAgIUJ9hQk3kXgZeZpY/m/0V6RmH1AbcwDQYJKoZIhvcNAQEL BQAwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM GEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMB4XDTI1MDEwMTAwMDAwMFoXDTM1 MDEwMTAwMDAwMFowRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUx ITAfBgNVBAoMGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMIIBIjANBgkqhkiG 9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4eXAMPLEcaPUBLIcfakeforopeNAPIspecON LYexampleCAcontentsoExpandedFakeKeyMaterial== -----END CERTIFICATE----- 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----- MIIDazCCAlOgAwIBAgIUJ9hQk3kXgZeZpY/m/0V6RmH1AbcwDQYJKoZIhvcNAQEL BQAwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM GEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMB4XDTI1MDEwMTAwMDAwMFoXDTM1 MDEwMTAwMDAwMFowRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUx ITAfBgNVBAoMGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMIIBIjANBgkqhkiG 9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4eXAMPLEcaPUBLIcfakeforopeNAPIspecON LYexampleCAcontentsoExpandedFakeKeyMaterial== -----END CERTIFICATE----- key: > -----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDh5cAWYXAMPLEbe fakekeyForOpenAPISpecPlaceholderOnlyDoNotUseForRealKeysNopeNopeNo peNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNo peNopeNopeNopeNopeNopeNope== -----END PRIVATE KEY----- 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----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDh5cAWYXAMPLEbe fakekeyForOpenAPISpecPlaceholderOnlyDoNotUseForRealKeysNopeNopeNo peNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNo peNopeNopeNopeNopeNopeNope== -----END PRIVATE KEY----- snis: - test.com id: '1' create_time: 1684373523 status: 1 cert: > -----BEGIN CERTIFICATE----- MIIDazCCAlOgAwIBAgIUJ9hQk3kXgZeZpY/m/0V6RmH1AbcwDQYJKoZIhvcNAQEL BQAwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM GEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMB4XDTI1MDEwMTAwMDAwMFoXDTM1 MDEwMTAwMDAwMFowRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUx ITAfBgNVBAoMGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMIIBIjANBgkqhkiG 9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4eXAMPLEcaPUBLIcfakeforopeNAPIspecON LYexampleCAcontentsoExpandedFakeKeyMaterial== -----END CERTIFICATE----- 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----- MIIDazCCAlOgAwIBAgIUJ9hQk3kXgZeZpY/m/0V6RmH1AbcwDQYJKoZIhvcNAQEL BQAwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM GEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMB4XDTI1MDEwMTAwMDAwMFoXDTM1 MDEwMTAwMDAwMFowRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUx ITAfBgNVBAoMGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMIIBIjANBgkqhkiG 9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4eXAMPLEcaPUBLIcfakeforopeNAPIspecON LYexampleCAcontentsoExpandedFakeKeyMaterial== -----END CERTIFICATE----- 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 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. > **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. **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 \ -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. **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"; package helloworld; service Greeter { rpc GetErrResp (HelloRequest) returns (HelloReply) {} } message HelloRequest { string name = 1; repeated string items = 2; } message HelloReply { string message = 1; repeated string items = 2; } message ErrorDetail { int64 code = 1; string message = 2; string type = 3; } '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"; package helloworld; service Greeter { rpc GetErrResp (HelloRequest) returns (HelloReply) {} } message HelloRequest { string name = 1; repeated string items = 2; } message HelloReply { string message = 1; repeated string items = 2; } message ErrorDetail { int64 code = 1; string message = 2; string type = 3; } 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"; package helloworld; service Greeter { rpc GetErrResp (HelloRequest) returns (HelloReply) {} } message HelloRequest { string name = 1; repeated string items = 2; } message HelloReply { string message = 1; repeated string items = 2; } message ErrorDetail { int64 code = 1; string message = 2; string type = 3; } 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"; package helloworld; service Greeter { rpc GetErrResp (HelloRequest) returns (HelloReply) {} } message HelloRequest { string name = 1; repeated string items = 2; } message HelloReply { string message = 1; repeated string items = 2; } message ErrorDetail { int64 code = 1; string message = 2; string type = 3; } 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. The `{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: >- The SNI hostname for matching the TLS passthrough routing. 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`.
When `hash_on` is set to `header` or `cookie`, `key` is required.
When `hash_on` is set to `vars` or `vars_combinations`, `key` is required and supports [built-in variables](/apisix/reference/built-in-variables).
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: >- Configure the host when the request is forwarded to the upstream. `pass` is used to pass the request's host to the upstream without modification. `node` sets the host to the host of the upstream node. `rewrite` sets the host to the value of `upstream_host`. upstream_host: 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: >- Type of value to hash on when `type` is `chash`. type: string name: description: Upstream name. type: string maxLength: 100 minLength: 1 scheme: enum: - grpc - grpcs - http - https - tcp - tls - udp - kafka default: http description: Protocol to communicate with the upstream. 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 default: false description: >- If true, verify the server certificate. Currently only Kafka upstream is supported. client_key: description: Private key. minLength: 128 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 type: object dependentSchemas: client_cert_id: not: required: - client_client - 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 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. type: object 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. Each 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 only when `deployment.config_provider` is `yaml`. Returns the entire current configuration document. 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: >- Replaces the entire current configuration. Available only when `deployment.config_provider` is `yaml`. requestBody: required: true content: application/json: schema: type: object application/yaml: schema: type: string responses: '200': description: Configuration applied. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' parameters: [] head: tags: - Standalone operationId: headStandaloneConfig summary: Probe standalone configuration availability description: >- Returns `200 OK` if the deployment is in YAML provider mode and the configuration endpoint is reachable. responses: '200': description: Standalone configuration is reachable. '401': $ref: '#/components/responses/Unauthorized' parameters: [] /apisix/admin/configs/validate: post: tags: - Standalone operationId: validateStandaloneConfig summary: Validate a standalone configuration without applying it description: >- Validates the supplied configuration document. The current configuration is not modified. requestBody: required: true content: application/json: schema: type: object application/yaml: schema: type: string responses: '200': description: Validation passed. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' parameters: [] /apisix/admin/routes/{id}/{sub_path}: parameters: - $ref: '#/components/parameters/IdInPath' - $ref: '#/components/parameters/SubPathInPath' patch: tags: - Routes operationId: patchRoutesSubPath summary: Replace a single nested field of a route description: >- Replaces the value at `sub_path` (slash-separated nested key path within the route document, e.g. `upstream/nodes`) with the request body. The body is any valid JSON value, not necessarily an object. parameters: - $ref: '#/components/parameters/Ttl' requestBody: required: true content: application/json: schema: {} 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' - $ref: '#/components/parameters/SubPathInPath' patch: tags: - Services operationId: patchServicesSubPath summary: Replace a single nested field of a service description: >- Replaces the value at `sub_path` (slash-separated nested key path within the service document, e.g. `upstream/nodes`) with the request body. The body is any valid JSON value, not necessarily an object. parameters: - $ref: '#/components/parameters/Ttl' requestBody: required: true content: application/json: schema: {} 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' - $ref: '#/components/parameters/SubPathInPath' patch: tags: - Upstreams operationId: patchUpstreamsSubPath summary: Replace a single nested field of a upstream description: >- Replaces the value at `sub_path` (slash-separated nested key path within the upstream document, e.g. `upstream/nodes`) with the request body. The body is any valid JSON value, not necessarily an object. parameters: - $ref: '#/components/parameters/Ttl' requestBody: required: true content: application/json: schema: {} 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' - $ref: '#/components/parameters/SubPathInPath' patch: tags: - SSL Certificates operationId: patchSSLCertificatesSubPath summary: Replace a single nested field of a SSL description: >- Replaces the value at `sub_path` (slash-separated nested key path within the SSL document, e.g. `upstream/nodes`) with the request body. The body is any valid JSON value, not necessarily an object. parameters: - $ref: '#/components/parameters/Ttl' requestBody: required: true content: application/json: schema: {} 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' - $ref: '#/components/parameters/SubPathInPath' patch: tags: - Consumer Groups operationId: patchConsumerGroupsSubPath summary: Replace a single nested field of a consumer group description: >- Replaces the value at `sub_path` (slash-separated nested key path within the consumer group document, e.g. `upstream/nodes`) with the request body. The body is any valid JSON value, not necessarily an object. parameters: - $ref: '#/components/parameters/Ttl' requestBody: required: true content: application/json: schema: {} 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' - $ref: '#/components/parameters/SubPathInPath' patch: tags: - Global Rules operationId: patchGlobalRulesSubPath summary: Replace a single nested field of a global rule description: >- Replaces the value at `sub_path` (slash-separated nested key path within the global rule document, e.g. `upstream/nodes`) with the request body. The body is any valid JSON value, not necessarily an object. parameters: - $ref: '#/components/parameters/Ttl' requestBody: required: true content: application/json: schema: {} 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' - $ref: '#/components/parameters/SubPathInPath' patch: tags: - Plugin Configs operationId: patchPluginConfigsSubPath summary: Replace a single nested field of a plugin config description: >- Replaces the value at `sub_path` (slash-separated nested key path within the plugin config document, e.g. `upstream/nodes`) with the request body. The body is any valid JSON value, not necessarily an object. parameters: - $ref: '#/components/parameters/Ttl' requestBody: required: true content: application/json: schema: {} 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: - $ref: '#/components/parameters/SecretType' - $ref: '#/components/parameters/IdInPath' - $ref: '#/components/parameters/SubPathInPath' patch: tags: - Secrets operationId: patchSecretSubPath summary: Replace a single nested field of a secret description: Replaces the value at `sub_path` within a secret object. requestBody: required: true content: application/json: schema: {} 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: **Map format** (shorthand): `{"host:port": weight}` **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: 128 maxLength: 65536 description: PEM-encoded client private key for mTLS with the upstream. verify: type: boolean default: false description: >- Whether to verify the upstream server's TLS certificate. Currently only supported for Kafka 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. An 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' 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. - `roundrobin` — Weighted round-robin distribution (default) - `chash` — Consistent hashing for session affinity - `ewma` — Latency-based (exponentially weighted moving average) - `least_conn` — Least number of active connections hash_on: type: string default: vars enum: - vars - header - cookie - consumer - vars_combinations description: |- What to hash on when `type` is `chash`. - `vars` — Hash on an NGINX variable (specified by `key`) - `header` — Hash on a request header (specified by `key`) - `cookie` — Hash on a cookie value (specified by `key`) - `consumer` — Hash on the authenticated consumer name - `vars_combinations` — Hash on a combination of variables key: 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 - tcp - tls - udp - kafka description: |- Protocol for communicating with upstream nodes. - L7: `http`, `https`, `grpc`, `grpcs` - L4: `tcp`, `tls`, `udp` - Special: `kafka` 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. - `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. Example: ```json { "limit-count": { "count": 100, "time_window": 60 }, "key-auth": {} } ``` See 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. A 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. `1` = enabled (default), `0` = disabled. 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. - `server` — For 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. `1` = enabled, `0` = disabled. 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. Plugins defined here run on every incoming request before route-specific plugins. 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 (for TLS connections). 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' additionalProperties: false 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. **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. - `server` — For 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. `1` = enabled, `0` = disabled. 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 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 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 SubPathInPath: name: sub_path in: path required: true schema: type: string description: Slash-separated nested key path within the resource document. example: upstream/nodes 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: false 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: 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: '`Route` configuration body for create / replace / patch.' required: true content: application/json: schema: $ref: '#/components/schemas/Route' 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: '`Service` configuration body for create / replace / patch.' required: true content: application/json: schema: $ref: '#/components/schemas/Service' 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: '`Upstream` configuration body for create / replace / patch.' required: true content: application/json: schema: $ref: '#/components/schemas/Upstream' 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: '`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 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----- MIIDazCCAlOgAwIBAgIUJ9hQk3kXgZeZpY/m/0V6RmH1AbcwDQYJKoZIhvcNAQEL BQAwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM GEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMB4XDTI1MDEwMTAwMDAwMFoXDTM1 MDEwMTAwMDAwMFowRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUx ITAfBgNVBAoMGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMIIBIjANBgkqhkiG 9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4eXAMPLEcaPUBLIcfakeforopeNAPIspecON LYexampleCAcontentsoExpandedFakeKeyMaterial== -----END CERTIFICATE----- key: | -----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDh5cAWYXAMPLEbe fakekeyForOpenAPISpecPlaceholderOnlyDoNotUseForRealKeysNopeNopeNo peNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNo peNopeNopeNopeNopeNopeNope== -----END PRIVATE KEY----- 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----- MIIDazCCAlOgAwIBAgIUJ9hQk3kXgZeZpY/m/0V6RmH1AbcwDQYJKoZIhvcNAQEL BQAwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM GEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMB4XDTI1MDEwMTAwMDAwMFoXDTM1 MDEwMTAwMDAwMFowRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUx ITAfBgNVBAoMGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMIIBIjANBgkqhkiG 9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4eXAMPLEcaPUBLIcfakeforopeNAPIspecON LYexampleCAcontentsoExpandedFakeKeyMaterial== -----END CERTIFICATE----- key: | -----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDh5cAWYXAMPLEbe fakekeyForOpenAPISpecPlaceholderOnlyDoNotUseForRealKeysNopeNopeNo peNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNo peNopeNopeNopeNopeNopeNope== -----END PRIVATE KEY----- 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: '`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 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: '`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 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"; package helloworld; service Greeter { rpc SayHello (HelloRequest) returns (HelloReply) {} } message HelloRequest { string name = 1; } message HelloReply { string message = 1; } ProtoUpsertPutId: description: '`Proto` configuration body for create / replace / patch.' required: true content: application/json: schema: $ref: '#/components/schemas/Proto' example: content: |- syntax = "proto3"; package helloworld; service Greeter { rpc SayHello (HelloRequest) returns (HelloReply) {} } message HelloRequest { string name = 1; } message HelloReply { string message = 1; } SecretUpsertPutCollection: description: Secret manager configuration (schema depends on `secret_type`). required: true content: application/json: schema: type: object additionalProperties: true SecretUpsertPatchCollection: description: Secret manager configuration (schema depends on `secret_type`). required: true content: application/json: schema: type: object additionalProperties: true security: - adminKey: [] - apiKeyQuery: [] - apiKeyCookie: []