REST API

NextList 前后端同构部署，全部能力都通过 HTTP API 暴露，第三方客户端（脚本、App、自动化）可以直接复用。本文给出端点地图与通用约定；请求 / 响应字段与前端源码（src/utils/api.ts、src/backend/server/*）一一对应。

通用约定 ​

Base URL：同域部署下为 /api。响应信封：除直链与 WebDAV 外，所有接口返回统一的 JSON 结构 { "code": 200, "message": "success", "data": ... }；code 为业务状态码（200 成功、403 密码错误、404 不存在、500 服务端异常），与 HTTP 状态码独立。认证：三种方式任选——登录签发的 JWT（Authorization: Bearer <token>，也接受 ?token= 查询参数，便于 / 直链场景）；管理面板「设置 → 其他」中的静态 API Token（同样走 Bearer 头，视为管理员）；未携带凭证且站点启用了 guest 账号时以游客身份访问。

登录示例 ​

curl -X POST https://your-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}'

返回 data.token 即 JWT，后续请求携带 Authorization: Bearer <token>。启用了两步验证的账号，登录请求会得到 code: 402，需在请求体追加 otp_code 重新提交。

端点地图 ​

认证与账户 ​

文件系统（/api/fs，除注明外均为 POST + JSON） ​

目录密码：受 Meta 保护（见高级设置）的路径，list / get 需携带 password，错误时返回 code: 403 与固定消息 password is incorrect or you have no permission（与 OpenList 一致）。

直链下载 ​

分享（/api/share） ​

公开端点（无需认证） ​

管理端点（/api/admin，需管理员） ​

MCP ​

POST /api/mcp（Streamable HTTP，推荐）、GET /api/mcp/sse + POST /api/mcp/messages（旧版 SSE）。协议方法与接入配置见 MCP 接入。

调用示例：列出目录 ​

TOKEN="<登录或静态令牌>"
curl -X POST https://your-domain.com/api/fs/list \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"/电影","page":1,"per_page":20}'

{
  "code": 200,
  "message": "success",
  "data": {
    "content": [
      { "name": "demo.mp4", "size": 1048576, "is_dir": false, "modified": "2026-01-01T00:00:00.000Z", "sign": "", "thumb": "", "type": 2 }
    ],
    "total": 1,
    "readme": "",
    "header": "",
    "write": true,
    "provider": "Quark"
  }
}