API · v1

接口文档

仪表盘能看到、能做的，脚本和 agent 都能通过 REST API 完成；数字与页面同一口径。

01认证

个人 API 令牌

在「设置 → API 令牌」创建令牌，然后放进请求头：

curl -H "Authorization: Bearer ew_…" \
  "{origin}/api/v1/situation?subscription=Acme&window=24h"

只读令牌只能调用 GET；读写令牌最多拥有其主人的角色。未开启账号的本机单用户安装无需令牌。

02约定

JSON

时间一律为 ISO-8601 UTC。
列表返回 {"data": [...], "page", "per_page", "total"}；每页最多 200。
错误返回 {"error": {"code", "message"}} 与 4xx 状态码。
提及用 item key 寻址："<来源>:<外部 id>"。

OpenAPI 3.1 JSON

03端点

17 个端点

方法	路径	说明	最低角色
`GET`	`/api/v1/me`	Who the token or session belongs to, its role and the API version	只读
`GET`	`/api/v1/situation`	Verdict, reasons, distance to the next level, top stories and the verifiable receipt for a scope `subscription` subscription id or exact name; empty = all mentions · `window` 24h \| 7d (default) \| 30d	只读
`GET`	`/api/v1/mentions`	Mentions with sentiment and triage state, newest scope first `q` full-text search · `subscription` subscription id or exact name; empty = all mentions · `source` source name, e.g. hn · `sentiment` pos \| neu \| neg · `status` new \| todo \| done \| ignored \| all (default: inbox) · `window` 24h \| 7d \| 30d (default) · `page` 1-based · `per_page` 1-200, default 50	只读
`PATCH`	`/api/v1/mentions/{key}`	Set a mention's triage status, tags and/or note body: `{"status": "todo\|done\|ignored\|new", "tags": ["..."], "note": "..."}`	编辑
`GET`	`/api/v1/subscriptions`	All subscriptions (structured queries)	只读
`POST`	`/api/v1/subscriptions`	Create a subscription body: `{"name": "Acme", "any_terms": ["Acme"], "all_terms": [], "exclude_terms": [], "sources": []}`	编辑
`PUT`	`/api/v1/subscriptions/{id}`	Replace a subscription body: `same as POST`	编辑
`DELETE`	`/api/v1/subscriptions/{id}`	Delete a subscription (and its alert rules)	编辑
`GET`	`/api/v1/alerts/levels`	The watch board: 24h level of every scope	只读
`GET`	`/api/v1/alerts/rules`	Alert rules (signing secrets are never returned)	只读
`POST`	`/api/v1/alerts/rules`	Create an alert rule; channel detected from the destination body: `{"subscription_id": 1, "min_level": "elevated", "destination": "https://open.feishu.cn/...", "channel": "auto\|json\|slack\|feishu\|dingtalk\|wecom\|email", "secret": "", "quiet_start": 22, "quiet_end": 7, "tz_offset_hours": 8, "weekend_mute": false}`	编辑
`DELETE`	`/api/v1/alerts/rules/{id}`	Delete an alert rule	编辑
`POST`	`/api/v1/alerts/rules/{id}/test`	Send a marked test digest over the rule's channel now	编辑
`GET`	`/api/v1/alerts/log`	Every evaluation and delivery outcome, newest first `limit` 1-500, default 50	只读
`GET`	`/api/v1/sources`	Per-source freshness and totals	只读
`GET`	`/api/v1/audit`	Who changed what, newest first `limit` 1-1000, default 100	只读
`GET`	`/api/v1/users`	People and roles	管理员