Project: APISIX (Orchestration & Management / API Gateway)
File: control-api.md

title: Control API <!-- --> In Apache APISIX, the control API is used to: Expose the internal state of APISIX. Control the behavior of a single, isolated APISIX data plane. To change the default endpoint (`127.0.0.1:9090`) of the Control API server, change the `ip` and `port` in the `control` section in your configuration file (`conf/config.yaml`): ```yaml apisix: ... enable_control: true control: ip: "127.0.0.1" port: 9090 ``` To enable parameter matching in plugin's control API, add `router: 'radixtreeuriwith_parameter'` to the control section. Note: Never configure the control API server to listen to public traffic. can be enabled to add its control API. Some Plugins have their own control APIs. See the documentation of the specific Plugin to learn more. The supported APIs are listed below. Introduced in . Returns the JSON schema used by the APISIX instance: ```json { "main": { "route": { "properties": {...} }, "upstream": { "properties": {...} }, ... }, "plugins": { "example-plugin": { "consumer_schema": {...}, "metadata_schema": {...}, "schema": {...}, "type": ..., "priority": 0, "version": 0.1 }, ... }, "stream-plugins": { "mqtt-proxy": { ... }, ... } } ``` Note: Only the enabled `plugins` are returned and they may lack fields like `consumer_schema` or `type` depending on how they were defined. Introduced in . Returns a of the APISIX instance. ```json [ { "nodes": [ { "ip": "52.86.68.46", "counter": { "http_failure": 0, "success": 0, "timeout_failure": 0, "tcp_failure": 0 }, "port": 80, "status": "healthy" }, { "ip": "100.24.156.8", "counter": { "http_failure": 5, "success": 0, "timeout_failure": 0, "tcp_failure": 0 }, "port": 80, "status": "unhealthy" } ], "name": "/apisix/routes/1", "type": "http" } ] ``` Each of the returned objects contain the following fields: name: resource id, where the health checker is reporting from. type: health check type: `["http", "https", "tcp"]`. nodes: target nodes of the health checker. nodes[i].ip: ip address. nodes[i].port: port number. nodes[i].status: health check result: `["healthy", "unhealthy", "mostlyhealthy", "mostlyunhealthy"]`. nodes[i].counter.success: success health check count. nodes[i].counter.http_failure: http failures count. nodes[i].counter.tcp_failure: tcp connect/read/write failures count. nodes[i].counter.timeout_failure: timeout count. You can also use `/v1/healthcheck/$srctype/$srcid` to get the health status of specific nodes. For example, `GET /v1/healthcheck/upstreams/1` returns: ```json { "nodes": [ { "ip": "52.86.68.46", "counter": { "http_failure": 0, "success": 2, "timeout_failure": 0, "tcp_failure": 0 }, "port": 80, "status": "healthy" }, { "ip":

"counter": { "http_failure": 5, "success": 0, "timeout_failure": 0, "tcp_failure": 0 }, "port": 80, "status": "unhealthy" } ], "type": "http" "name": "/apisix/routes/1" } ``` :::note Only when one upstream is satisfied by the conditions below, its status is shown in the result list: The upstream is configured with a health checker The upstream has served requests in any worker process ::: If you use browser to access the control API URL, then you will get the HTML output: Introduced in . Triggers a full garbage collection in the HTTP subsystem. Note: When stream proxy is enabled, APISIX runs another Lua VM for the stream subsystem. Full garbage collection is not triggered in this VM. Introduced in . Returns all configured : ```json [ { "value": { "priority": 0, "uris": [ "/hello" ], "id": "1", "upstream": { "scheme": "http", "pass_host": "pass", "nodes": [ { "port": 1980, "host": "127.0.0.1", "weight": 1 } ], "type": "roundrobin", "hash_on": "vars" }, "status": 1 }, "clean_handlers": {}, "has_domain": false, "orig_modifiedIndex": 1631193445, "modifiedIndex": 1631193445, "key": "/routes/1" } ] ``` Introduced in . Returns the Route with the specified `route_id`: ```json { "value": { "priority": 0, "uris": [ "/hello" ], "id": "1", "upstream": { "scheme": "http", "pass_host": "pass", "nodes": [ { "port": 1980, "host": "127.0.0.1", "weight": 1 } ], "type": "roundrobin", "hash_on": "vars" }, "status": 1 }, "clean_handlers": {}, "has_domain": false, "orig_modifiedIndex": 1631193445, "modifiedIndex": 1631193445, "key": "/routes/1" } ``` Introduced in . Returns all the Services: ```json [ { "has_domain": false, "clean_handlers": {}, "modifiedIndex": 671, "key": "/apisix/services/200", "createdIndex": 671, "value": { "upstream": { "scheme": "http", "hash_on": "vars", "pass_host": "pass", "type": "roundrobin", "nodes": [ { "port": 1980, "weight": 1, "host": "127.0.0.1" } ] }, "create_time": 1634552648, "id": "200", "plugins": { "limit-count": { "key": "remote_addr", "time_window": 60, "redis_timeout": 1000, "allow_degradation": false, "showlimitquota_header": true, "policy": "local", "count": 2, "rejected_code": 503 } }, "update_time": 1634552648 } } ] ``` Introduced in . Returns the Service with the specified `service_id`: ```json { "has_domain": false, "clean_handlers": {}, "modifiedIndex": 728, "key": "/apisix/services/5", "createdIndex": 728, "value": { "create_time": 1634554563, "id": "5", "upstream": { "scheme": "http", "hash_on": "vars", "pass_host": "pass", "type": "roundrobin", "nodes": [ { "port": 1980, "weight": 1, "host": "127.0.0.1" } ] }, "update_time": 1634554563 } } ``` Introduced in . Dumps all Upstreams: ```json [ { "value":{ "scheme":"http", "pass_host":"pass", "nodes":[ { "host":"127.0.0.1", "port":80, "weight":1 }, { "host":"foo.com", "port":80, "weight":2 } ], "hash_on":"vars", "update_time":1634543819, "key":"remote_addr", "create_time":1634539759, "id":"1", "type":"chash" }, "has_domain":true, "key":"\/apisix\/upstreams\/1", "clean_handlers":{ }, "createdIndex":938, "modifiedIndex":1225 } ] ``` Introduced in . Dumps the Upstream with the specified `upstream_id`: ```json { "value":{ "scheme":"http", "pass_host":"pass", "nodes":[ { "host":"127.0.0.1", "port":80, "weight":1 }, { "host":"foo.com", "port":80, "weight":2 } ], "hash_on":"vars", "update_time":1634543819, "key":"remote_addr", "create_time":1634539759, "id":"1", "type":"chash" }, "has_domain":true, "key":"\/apisix\/upstreams\/1", "clean_handlers":{ }, "createdIndex":938, "modifiedIndex":1225 } ``` Introduced in . Dumps all plugin_metadatas: ```json [ { "log_format": { "upstreamresponsetime": "$upstreamresponsetime" }, "id": "file-logger" }, { "ikey": 1, "skey": "val", "id": "example-plugin" } ] ``` Introduced in . Dumps the metadata with the specified `plugin_name`: ```json { "log_format": { "upstreamresponsetime": "$upstreamresponsetime" }, "id": "file-logger" } ``` Introduced in Triggers a hot reload of the plugins. ```shell curl "http://127.0.0.1:9090/v1/plugins/reload" -X PUT ```