API · v1
API reference
Everything the dashboard shows and does is available to scripts and agents over REST, with the same numbers and calibers.
01Authentication
Personal API tokens
Create a token under Settings → API tokens, then send it as a header:
curl -H "Authorization: Bearer ew_…" \
"{origin}/api/v1/situation?subscription=Acme&window=24h"
Read tokens can only call GET; write tokens never exceed their owner's role. A local single-user install without accounts needs no token.
02Conventions
JSON
- Times are ISO-8601 UTC.
- Lists return {"data": [...], "page", "per_page", "total"}; at most 200。
- Errors return {"error": {"code", "message"}} with a 4xx status.
- Mentions are addressed by item key: "<source>:<external id>".
03Endpoints
17 endpoints
| Method | Path | Description | Minimum role |
|---|---|---|---|
GET | /api/v1/me |
Who the token or session belongs to, its role and the API version | Viewer |
GET | /api/v1/situation |
Verdict, reasons, distance to the next level, top stories and the verifiable receipt for a scopesubscription subscription id or exact name; empty = all mentions · window 24h | 7d (default) | 30d
|
Viewer |
GET | /api/v1/mentions |
Mentions with sentiment and triage state, newest scope firstq 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
|
Viewer |
PATCH | /api/v1/mentions/{key} |
Set a mention's triage status, tags and/or note
body: {"status": "todo|done|ignored|new", "tags": ["..."], "note": "..."} |
Edit |
GET | /api/v1/subscriptions |
All subscriptions (structured queries) | Viewer |
POST | /api/v1/subscriptions |
Create a subscription
body: {"name": "Acme", "any_terms": ["Acme"], "all_terms": [], "exclude_terms": [], "sources": []} |
Edit |
PUT | /api/v1/subscriptions/{id} |
Replace a subscription
body: same as POST |
Edit |
DELETE | /api/v1/subscriptions/{id} |
Delete a subscription (and its alert rules) | Edit |
GET | /api/v1/alerts/levels |
The watch board: 24h level of every scope | Viewer |
GET | /api/v1/alerts/rules |
Alert rules (signing secrets are never returned) | Viewer |
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} |
Edit |
DELETE | /api/v1/alerts/rules/{id} |
Delete an alert rule | Edit |
POST | /api/v1/alerts/rules/{id}/test |
Send a marked test digest over the rule's channel now | Edit |
GET | /api/v1/alerts/log |
Every evaluation and delivery outcome, newest firstlimit 1-500, default 50
|
Viewer |
GET | /api/v1/sources |
Per-source freshness and totals | Viewer |
GET | /api/v1/audit |
Who changed what, newest firstlimit 1-1000, default 100
|
Viewer |
GET | /api/v1/users |
People and roles | Admin |