Manage

API reference

Call FengSui from scripts, dashboards and home automation with a token: how to authenticate, the endpoints and what they return, live events and Prometheus metrics.

FengSui's web console runs on this REST API. Scripts, dashboards and home automation can call the same endpoints with a token: read the signal and its history, refresh now, lock bands, send and read SMS, or follow live events.

For AI agents, use MCP instead: it adds switches, confirmations and tighter limits on top of this API.

#Get a token

Create a token in the console under Settings → Tokens & AI. It is shown once, so copy it right away. You can give it a lifetime (1 to 365 days, or none) and revoke it at any time (see Security and privacy).

Every token can read the router's data and have FengSui refresh it now. Anything else needs a permission, ticked when you create the token or later with "Permissions" on an existing one under Settings → Tokens & AI:

No token can change the console's settings (the sign-in password, tokens, the router connection, the switches) or delete messages in Recently deleted for good; only a signed-in console can (403 CONSOLE_ONLY). The endpoints the console uses for itself (/api/auth/*, /api/setup/*, /api/console/*) are closed to tokens and not listed below.

#Make a request

Put the token in the Authorization header:

# Read
curl -H "Authorization: Bearer <token>" http://<NAS IP>:18384/api/telemetry

# Change something: POST with a JSON body
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"mode":"auto"}' \
  http://<NAS IP>:18384/api/control/antenna

• Every POST needs Content-Type: application/json; send {} when there are no parameters. A body may be up to 64 KiB (4 MiB for a contacts import).
• Reading never signs in to the router. A GET answers from FengSui's latest data in memory, so you can call it often. By default FengSui reads the signal every 5 seconds (POLL_INTERVAL_MS) and scans nearby cells and connected devices every 60 seconds (NEIGHBOR_SCAN_INTERVAL_MS); see Configuration.
• Refreshing and changing sign in to the router. The router allows one admin session at a time, so FengSui queues every request and runs them one by one. Do not call the refresh endpoints in a tight loop.
• FengSui steps aside while someone is signed in to the router's own page: a refresh or change then answers 409 BROWSER_SESSION_YIELDED and does nothing.
• When you use a host name (behind a reverse proxy, say), add it to ALLOWED_HOSTS, or requests answer 421 MISDIRECTED_HOST (see Security and privacy).
• Token requests need no X-Requested-With. Only a browser calling with the console's sign-in cookie needs it, as the cross-site request forgery (CSRF) check.
• Identifiers are masked by default. With a token, the IMEI keeps its first 6 digits, the IMSI its operator code, numbers, MACs and WAN addresses only a part, and cell identities and device names are hidden (REDACT_SENSITIVE_IN_API=true). The signed-in console sees the real values.

#Answers and errors

A success answers 200 with ok: true and the data in fields next to it. A band lock, for example, answers (shortened):

{ "ok": true, "lockState": { "mode": "band_lock", "lteBands": [1, 3], "nrBands": [] } }

A failure answers with its HTTP status and ok: false:

{ "ok": false, "errorCode": "VALIDATION_ERROR", "message": "…" }

Have scripts go by errorCode, never by message: the message may be in Chinese or English, and its wording changes. The error codes a script can meet:

#Endpoints

The Permission column names what a token needs beyond reading. The request and answer fields of each endpoint are in the developer notes' API contract (in Chinese).

#Reading

#Refreshing

#Router controls

#Devices' internet access

#SMS

#Other

The endpoints that change the router follow the console's rules: on a router that was not verified, a write FengSui does not implement answers 409 DEVICE_UNVERIFIED_READ_ONLY, and one you turned off under Settings → Device answers 409 DEVICE_WRITE_DISABLED; neither sends the router anything (see Other models and brands).

#Live events

GET /api/events is a Server-Sent Events stream. It opens with a hello (the current state) and then sends whatever changes:

curl -N -H "Authorization: Bearer <token>" http://<NAS IP>:18384/api/events

Each message has an event: (the name) and a data: line of JSON. Every 15 seconds a heartbeat line starting with : keeps the connection open (SSE_HEARTBEAT_MS); clients ignore it. After a reconnect you get a new hello; FengSui does not replay what was sent while you were away.

• Connections are limited: SSE_MAX_CLIENTS in all (32 by default) and 6 per address; past that, 429 SSE_LIMIT_REACHED.
• When a token is revoked or expires, the streams it opened close at once.

#Prometheus metrics

Turn them on in the console under Settings → Security (or set METRICS_ENABLED=true in .env), and GET /metrics answers in the Prometheus text format: the signal (RSRP, RSRQ, SINR), carriers and bandwidth, rates, traffic, the WAN state, SMS counts, sessions and the queue, and FengSui's own memory, CPU and event-loop delay. The metrics carry no device identifiers. While they are off, /metrics answers 404.

Any token can read the metrics; no permission is needed. A Prometheus scrape configuration:

scrape_configs:
  - job_name: fengsui
    metrics_path: /metrics
    authorization:
      credentials: <token>
    static_configs:
      - targets: ["<NAS IP>:18384"]

#Liveness check

GET /api/health needs no token and answers with the version and uptime, for uptime monitors. The Docker image's own health check uses it too.

Edit this page on GitHub