# API

Base URL: `http://<host>:<apiPort>`

When `server.password` is configured, every request except those marked as public
must include an `Authorization: Bearer <token>` header.

## Authentication

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/auth` | Return `{ required, authenticated }` |
| POST | `/api/auth` | Log in with body `{ "password": "xxx" }`; returns `{ token }` |
| DELETE | `/api/auth` | Log out the current session |

## Status

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/status` | Return uptime, sing-box process status, and the active node for each policy |
| GET | `/api/endpoints` | Return endpoints and their active nodes |

## Backends

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/backends` | Return all backend states, including node counts, last update times, and errors |
| GET | `/api/backends/:name` | Return details for one backend |
| POST | `/api/backends/refresh` | Refresh all backends |
| POST | `/api/backends/:name/refresh` | Refresh one backend |

## Policies and Nodes

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/policies` | Return policies, active nodes, and last speed-test times |
| POST | `/api/policies/:name/switch` | Manually switch nodes with body `{ "node": "node-name" }` |
| POST | `/api/policies/:name/speedtest` | Run a speed test and return latency results for all nodes |
| GET | `/api/health` | Return node health data grouped by policy: `{ policyName: { nodeName: health } }` |

## Subscription URLs

All subscription URLs are public endpoints and are not protected by the management
password. Each group can have its own subscription password.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/subscriptions` | Public. Return all subscription groups, their enabled formats, and passwords |
| GET | `/api/subscribe/clash/:groupName` | Public. Return the Clash configuration (YAML) for a group; see supported parameters below |
| GET | `/api/subscribe/clash/:groupName/toggles` | Return the routing-rule toggle states for a group |
| PUT | `/api/subscribe/clash/:groupName/toggles` | Update routing-rule toggles with body `{ "cnDirect": false }` |
| GET | `/api/subscribe/shadowrocket/:groupName` | Public. Return the Shadowrocket node list (Base64) for a group |

### Clash Subscription Parameters

`/api/subscribe/clash/:groupName` supports the following query parameters:

| Parameter | Description |
|-----------|-------------|
| `password` | Subscription password, when `clash.password` is configured for the group |
| `cnDirect` | `1`/`0`; temporarily override direct access to China |
| `adBlock` | `1`/`0`; temporarily override ad blocking |
| `private` | `1`/`0`; temporarily override direct access to private networks |

Without query parameters, the server's current toggle states are used. They can
be changed through the web UI or the toggle `PUT` endpoint.