⚡ Agent 接入文档

通过一个 HTTP 请求把结果推给用户. 单 Key = 单用户.

1. 拿到 API Key

Key 格式: ak_xxxxxxxxxxxx

2. 调用 `/notify`

所有字段:

字段	必填	说明
`title`	✓	标题, ≤200 字符
`body`		正文. `type=html` 时会被 DOMPurify 清洗 (script/iframe 移除)
`type`		`text`(默认) / `md` / `html` / `link`
`url`		`type=link` 时附带的链接; http(s) 协议白名单
`ttl`		消息存活秒数 (覆盖默认保留期), 上限 365 天

curl

curl -X POST https://notify.ztsy.top/notify \
  -H "X-API-Key: ak_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "任务完成",
    "body": "agent 跑完了, 结果在附件",
    "type": "text"
  }'

Python (requests)

import requests
requests.post(
    "https://notify.ztsy.top/notify",
    headers={"X-API-Key": "ak_xxxxxxxxxxxx"},
    json={"title": "任务完成", "body": "结果...", "type": "text"},
)

JavaScript (fetch)

await fetch("https://notify.ztsy.top/notify", {
  method: "POST",
  headers: {
    "X-API-Key": "ak_xxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ title: "任务完成", body: "结果...", type: "text" }),
});

3. 响应

成功 (200):

{
  "id": 1234,
  "delivered": false,
  "online": 0,
  "quota": { "used": 5, "limit": 100000 }
}

online 是当前 WebSocket 在线客户端数 (Android 走 MQTT, 不计入).

4. type 类型

text — 纯文本 (默认)
md — Markdown (客户端用 Markwon 渲染, 支持标题/列表/代码块/链接)
html — HTML (后端 DOMPurify 清洗 + 客户端 WebView 沙箱渲染, 禁 JS)
link — 链接消息 (点击打开 url)

5. 错误码

HTTP	error	说明
401	`invalid_api_key`	Key 不存在/已撤销
400	`title_required`	title 为空
400	`invalid_type`	type 不是 text/md/html/link
400	`unsafe_url`	url 协议不是 http(s)
413	`body_too_large`	body 超过 max_body_size
429	`rate_limited`	触发限流 (IP/用户/Key 维度)
429	`quota_exceeded`	每日配额用完 (free 1000/天, vip 100000/天)

6. 限流 / 配额

IP: 默认 60 req/min
用户: free 60 req/min, vip 600 req/min
Key: 默认 300 req/min
每日配额: free 1000 条/天, vip 100000 条/天

7. 机器可读文档

agent 可拉 /api/docs 拿 JSON 格式的同样信息 (字段定义 + 错误码).

服务器地址: https://notify.ztsy.top · 登录 · 健康检查