Clash / Mihomo Controller API Docs - Full RESTful Reference

Example Request

Every request a dashboard or script sends to the core must include an authentication header, formatted as follows:

curl Shell

curl -H 'Authorization: Bearer ${secret}' http://${controller-api}/configs?force=true \
  -d '{"path": "", "payload": ""}' -X PUT

${secret} is the secret key set in your config file
${controller-api} is the external-controller listen address set in your config file
?force=true is a query parameter required by some endpoints
'{"path": "", "payload": ""}' is the resource data to update

If a request needs to pass a file path that isn't inside the mihomo working directory, you'll need to manually set the SAFE_PATHS environment variable to add it to the allowed paths. The syntax matches your OS's PATH variable (semicolon-separated on Windows, colon-separated elsewhere).

Logs

GETWS/logs

Get real-time logs.

Optional parameter ?level=log_level, where log_level can be info/warning/error/debug
Optional parameter ?format=structured; when included, outputs structured logs (with time/level/message/fields)
Standard mode pushes one JSON object per line: type is the log level, payload is the log message
Structured mode: time (HH:MM:SS), level, message, fields (array of extra fields)

Traffic Info

GETWS/traffic

Get real-time traffic. up/down are in bytes/second, upTotal/downTotal are in bytes, pushed once per second.

up current upload rate　down current download rate
upTotal cumulative bytes uploaded　downTotal cumulative bytes downloaded

Memory Info

GETWS/memory

Get real-time memory usage (in bytes), pushed once per second.

inuse current memory in use　oslimit system memory limit (always 0)

Version Info

GET/version

Get core version info.

meta whether this is a Meta build　version version string

Cache

POST/cache/fakeip/flush

Clear the fake-ip cache. Returns HTTP 204.

POST/cache/dns/flush

Clear the DNS cache. Returns HTTP 204.

Runtime Config

GET/configs

Get the current running config as a JSON object, including fields like port, socks-port, mixed-port, mode, log-level, allow-lan, ipv6, tun, and more.

PUT/configs

Reload the base config, with the parameter ?force=true. Returns HTTP 204.

PATCH/configs

Partially update the base config, e.g. '{"mixed-port": 7890}'. Returns HTTP 204.

POST/configs/geo

Update the GEO database, with '{"path": "", "payload": ""}'. Returns HTTP 204.

POST/restart

Restart the core, with '{"path": "", "payload": ""}'. Returns HTTP 204.

Updates

POST/upgrade

Update the core. Optional ?channel=xxx to specify an update channel, or ?force=true to force the update. Returns {"status": "ok"}.

POST/upgrade/ui

Update the dashboard (requires external-ui to be set in the config first). Returns {"status": "ok"}.

POST/upgrade/geo

Update the GEO database. Returns HTTP 204.

Proxy Groups

GET/group

Get info for all proxy groups. Returns a proxies array, each item formatted the same as /proxies/{name}.

GET/group/{group_name}

Get info for a specific proxy group, formatted the same as /proxies/{name}.

GET/group/{group_name}/delay

Test the latency of every node in the proxy group. Returns fresh latency data and clears any current fixed selection on the auto-select group.

Include the parameters ?url=xxx&timeout=5000
Optional ?expected=xxx: the expected HTTP status code, supports range syntax like 200/204 or 200-299
Returns an object mapping node names to latency in milliseconds, e.g. {"NodeA": 120, "NodeB": 350}

Proxies

GET/proxies

Get info for all proxies/proxy groups. Returns a proxies object keyed by name; common fields for every entry include:

name/type (e.g. Shadowsocks, VMess, DIRECT, Selector, URLTest, etc.)
udp/uot/xudp/tfo/mptcp/smux capability flags
alive whether it's currently reachable, history latency history (time + delay), extra additional history grouped by test URL
interface/routing-mark/provider-name/dialer-proxy
Proxy groups also include: now the currently selected node (not present on LoadBalance), all the member list, testUrl, hidden, icon, emptyFallback, expectedStatus (not present on Selector), fixed (URLTest/Fallback only)

GET/proxies/{name}

Get info for a specific proxy/proxy group, with the same fields as above (a plain proxy only has the common fields).

PUT/proxies/{name}

Switch the currently selected node in this proxy group. Include '{"name":"Japan"}'. Returns HTTP 204.

DELETE/proxies/{name}

Clear the fixed selection for this proxy/proxy group (not applicable to the Selector type). Returns HTTP 204.

GET/proxies/{name}/delay

Test the latency of a specific proxy. Include ?url=xxx&timeout=5000 (optionally ?expected=xxx). Returns {"delay": 120}.

Proxy Providers

GET/providers/proxies

Get info for all proxy providers. Returns a providers object keyed by provider name, each containing metadata and a list of proxies.

GET/providers/proxies/{name}

Get info for a specific proxy provider, including its config info and a proxies list.

PUT/providers/proxies/{name}

Update this proxy provider. Returns HTTP 204.

GET/providers/proxies/{name}/healthcheck

Trigger a health check for this proxy provider. Returns HTTP 204.

GET/providers/proxies/{name}/{proxy_name}

Get info for a specific proxy within a provider, with the same fields as /proxies/{name}.

GET/providers/proxies/{name}/{proxy_name}/healthcheck

Test the latency of a specific proxy within a provider. Include ?url=xxx&timeout=5000. Returns {"delay": 120}.

Rules

GET/rules

Get all rules. Returns a rules array, each item containing:

index index (0-based)　type rule type　payload match content　proxy target proxy/proxy group
size number of entries in the rule (only meaningful for GEOIP/GEOSITE, otherwise -1)
Optional extra: disabled/hitCount/hitAt/missCount/missAt

PATCH/rules/disable

Temporarily enable/disable rules by index (resets on restart). Include '{"0": false,"1": true}'. Returns HTTP 204.

Rule Providers

GET/providers/rules

Get info for all rule providers. Returns a providers object keyed by name.

PUT/providers/rules/{name}

Update a specific rule provider. Returns HTTP 204.

Connections

GETWS/connections

Get active connection info. Optional parameter ?interval=milliseconds (refresh interval, defaults to 1000ms).

downloadTotal/uploadTotal cumulative traffic　memory current memory usage
connections array of active connections: id, metadata (source/destination address, protocol, process name, etc.), upload/download, start, chains/providerChains the proxy chain, rule/rulePayload the matched rule

DELETE/connections

Close all connections. Returns HTTP 204.

DELETE/connections/{id}

Close a specific connection. Returns HTTP 204.

DNS Query

GET/dns/query

Get a DNS query result for a given name and type. Include ?name=example.com&type=A.

Status DNS response code　Question array of query questions
TC/RD/RA/AD/CD various DNS flag bits
Optional Answer/Authority/Additional: arrays of records, each with name/type/TTL/data

Storage

GET/storage/{key}

Get the stored value for a given key. Returns null if it doesn't exist.

PUT/storage/{key}

Write a value for a given key (must be valid JSON, max 1MB). Include '{"foo": "bar"}'. Returns HTTP 204.

DELETE/storage/{key}

Delete the stored value for a given key. Returns HTTP 204.

DEBUG

The /debug endpoints require the core's startup log level to be set to debug.

PUT/debug/gc

Trigger a manual garbage collection. Returns HTTP 204.

GET/debug/pprof

Open http://${controller-api}/debug/pprof in your browser to view raw debug info:

allocs: memory allocations per function call (stack/heap size and count), useful for tracking down memory leaks or frequent allocations
heap: detailed heap memory usage, including the size, count, and address of allocated blocks sorted by size, useful for locating high memory usage

Install Graphviz to view a graphical report:

Shell pprof

go tool pprof -http=:8080 http://127.0.0.1:xxxx/debug/pprof/heap
go tool pprof -http=:8080 http://127.0.0.1:xxxx/debug/pprof/allocs

Visit http://${controller-api}/debug/pprof/heap?raw=true in your browser to download the report file — attach it to an issue if you need help troubleshooting.