接口
下面这些都需要 API Key。响应统一是 {"ok":true,"data":…} 的信封。
节点相关接口不在本页
节点清单与取配置这两个接口会返回真实节点信息，只对单独授权过的 Key 开放，
因此不写进公开文档。需要对接时联系站长单独开通。
GET
/api/v1/ext/account
账号概览：状态、设备数、以及名下所有套餐（含到期、用量、能否连接）。
{
"ok": true,
"data": {
"accountId": "you@example.com",
"email": "you@example.com",
"qq": "12345678",
"status": "active",
"createdAt": 1792064568,
"deviceLimit": 2,
"devices": 1,
"plans": [
{
"grantId": "g_xxxxxxxxxx",
"title": "标准套餐",
"planName": "standard",
"serviceStatus": "normal",
"expiresAt": 1794656567,
"remainingDays": 30,
"trafficLimit": 107374182400,
"usedBytes": 21474836480,
"remainingBytes": 85899345920,
"deviceLimit": 2,
"canConnect": true,
"denyReason": ""
}
],
"traffic": { "unlimited": false, "limitBytes": 107374182400, "usedBytes": 21474836480, "remainingBytes": 85899345920 },
"expiry": { "expiresAt": 1794656567, "remainingDays": 30 },
"invite": {
"enabled": true,
"code": "A1B2C3D4",
"link": "https://clash.cupzz.cn/register?invite=A1B2C3D4",
"invitedCount": 3,
"notice": "",
"inviterReward": "每邀请 1 人：+10 GB 流量",
"inviteeReward": "被邀请注册：+5 GB 流量"
}
}
}
canConnect 为 false 时 denyReason 会说明原因
（到期 / 流量用尽 / 被停用等）。流量单位是字节。
traffic 与 expiry 是整个账号的汇总（多条套餐相加；
有任意一条不限流量时 unlimited 为 true 且两个额度字段为 -1，
expiry 取最近到期的那条，那才是"什么时候会断"）。
POST
/api/v1/ext/query/code
给目标账号的邮箱发一个查询验证码。邮箱由服务端配置的发件邮箱发出，
你无法指定发件人。响应永远是同一句话（不暴露该邮箱是否在本站注册过）。
curl -X POST https://clash.cupzz.cn/api/v1/ext/query/code \
-H "Authorization: Bearer cncp_你的密钥" \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com"}'
{"ok":true,"data":{"sent":true,"message":"如果该邮箱已注册，验证码已发出。","serverTime":1792064613}}
站点没有开启邮箱验证码时返回 403：这条路径不会被悄悄放行，
因为那等于开了一个不需要凭据的账号查询入口。
POST
/api/v1/ext/query
查询指定账号（不只是你自己的）。必须出示目标账号的密码或上面那个验证码，
两者给其一即可。返回的内容与 账号接口 完全一致。
curl -X POST https://clash.cupzz.cn/api/v1/ext/query \
-H "Authorization: Bearer cncp_你的密钥" \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com","password":"该账号的密码"}'
# 或者用验证码：
curl -X POST https://clash.cupzz.cn/api/v1/ext/query \
-H "Authorization: Bearer cncp_你的密钥" \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com","code":"123456"}'
凭据不对与"该邮箱没有账号"返回完全相同的响应
（401 unauthorized），失败次数与网页登录共用同一套限速，
换个入口多试几次是不行的。验证码一次性、有有效期，且只发给已注册的邮箱。
GET
/api/v1/ext/devices
自己账号下的设备列表。
{
"ok": true,
"data": {
"devices": [
{
"deviceId": "d_1a2b3c…",
"name": "我的手机",
"platform": "android",
"status": "active",
"createdAt": 1792064568,
"lastSeenAt": 1792064600
}
]
}
}
POST
/api/v1/ext/devices/register
登记一台设备。登记后会自动绑定到你的账号并激活（受设备数上限约束，
与客户端登录时的规则一致）。
curl -X POST https://clash.cupzz.cn/api/v1/ext/devices/register \
-H "Authorization: Bearer cncp_你的密钥" \
-H "Content-Type: application/json" \
-d '{
"deviceId": "d_你的设备标识",
"publicKey": "base64 编码的 X25519 公钥",
"keyId": "k1_公钥指纹",
"name": "我的脚本"
}'
{"ok":true,"data":{"deviceId":"d_…","status":"active","created":true,"serverTime":1792064568}}
deviceId 与 publicKey 必填；keyId、
name 可选。公钥用于加密下发给该设备的配置。
POST
/api/v1/ext/devices/remove
移除自己账号下的一台设备，该设备的登录状态会立刻失效。
curl -X POST https://clash.cupzz.cn/api/v1/ext/devices/remove \
-H "Authorization: Bearer cncp_你的密钥" \
-H "Content-Type: application/json" \
-d '{"deviceId":"d_要移除的设备"}'
{"ok":true,"data":{"removed":true}}
GET
/api/v1/ext/usage
这把 Key 的配额与最近的调用统计（按天聚合）。
{
"ok": true,
"data": {
"keyPrefix": "cncp_a1b2c3",
"label": "给对账脚本用",
"quotaMode": "period",
"quotaPeriod": "month",
"quotaLimit": 10000,
"used": 42,
"remaining": 9958,
"resetAt": 1794742968,
"expiresAt": 0,
"lastUsedAt": 1792064613,
"calls": [
{ "day": "2026-10-15", "endpoint": "/api/v1/ext/account", "calls": 12 }
],
"serverTime": 1792064613
}
}
remaining 为 -1 表示不限次数；
resetAt 为 0 表示没有"重置"这回事（total 模式）。
公开接口（不需要 Key）
GET
/api/v1/stats
站点实时统计，客户端底部那条数据用的就是它。
{"ok":true,"data":{"onlineUsers":12,"todayConnections":378,"totalConnections":9723}}
GET
/api/v1/meta
站点配置：名称、公告、下载地址、联系方式、版本要求等。