{"openapi":"3.1.0","info":{"title":"EchoWatch API","version":"v1","description":"Listening data and actions. Authenticate with a personal API token: Authorization: Bearer ew_... (create one under Settings > API tokens)."},"servers":[{"url":"/"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"paths":{"/api/v1/me":{"get":{"summary":"Who the token or session belongs to, its role and the API version","tags":["Account"],"description":"Requires role: viewer.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/situation":{"get":{"summary":"Verdict, reasons, distance to the next level, top stories and the verifiable receipt for a scope","tags":["Situation"],"description":"Requires role: viewer.","parameters":[{"name":"subscription","in":"query","required":false,"description":"subscription id or exact name; empty = all mentions","schema":{"type":"string"}},{"name":"window","in":"query","required":false,"description":"24h | 7d (default) | 30d","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/mentions":{"get":{"summary":"Mentions with sentiment and triage state, newest scope first","tags":["Mentions"],"description":"Requires role: viewer.","parameters":[{"name":"q","in":"query","required":false,"description":"full-text search","schema":{"type":"string"}},{"name":"subscription","in":"query","required":false,"description":"subscription id or exact name; empty = all mentions","schema":{"type":"string"}},{"name":"source","in":"query","required":false,"description":"source name, e.g. hn","schema":{"type":"string"}},{"name":"sentiment","in":"query","required":false,"description":"pos | neu | neg","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"new | todo | done | ignored | all (default: inbox)","schema":{"type":"string"}},{"name":"window","in":"query","required":false,"description":"24h | 7d | 30d (default)","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"1-based","schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"description":"1-200, default 50","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/mentions/{key}":{"patch":{"summary":"Set a mention's triage status, tags and/or note","tags":["Mentions"],"description":"Requires role: editor.","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":"{\"status\": \"todo|done|ignored|new\", \"tags\": [\"...\"], \"note\": \"...\"}"}}}}},"/api/v1/subscriptions":{"get":{"summary":"All subscriptions (structured queries)","tags":["Subscriptions"],"description":"Requires role: viewer.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Create a subscription","tags":["Subscriptions"],"description":"Requires role: editor.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":"{\"name\": \"Acme\", \"any_terms\": [\"Acme\"], \"all_terms\": [], \"exclude_terms\": [], \"sources\": []}"}}}}},"/api/v1/subscriptions/{id}":{"put":{"summary":"Replace a subscription","tags":["Subscriptions"],"description":"Requires role: editor.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":"same as POST"}}}},"delete":{"summary":"Delete a subscription (and its alert rules)","tags":["Subscriptions"],"description":"Requires role: editor.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/alerts/levels":{"get":{"summary":"The watch board: 24h level of every scope","tags":["Alerts"],"description":"Requires role: viewer.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/alerts/rules":{"get":{"summary":"Alert rules (signing secrets are never returned)","tags":["Alerts"],"description":"Requires role: viewer.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Create an alert rule; channel detected from the destination","tags":["Alerts"],"description":"Requires role: editor.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":"{\"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}"}}}}},"/api/v1/alerts/rules/{id}":{"delete":{"summary":"Delete an alert rule","tags":["Alerts"],"description":"Requires role: editor.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/alerts/rules/{id}/test":{"post":{"summary":"Send a marked test digest over the rule's channel now","tags":["Alerts"],"description":"Requires role: editor.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/alerts/log":{"get":{"summary":"Every evaluation and delivery outcome, newest first","tags":["Alerts"],"description":"Requires role: viewer.","parameters":[{"name":"limit","in":"query","required":false,"description":"1-500, default 50","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/sources":{"get":{"summary":"Per-source freshness and totals","tags":["Sources"],"description":"Requires role: viewer.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/audit":{"get":{"summary":"Who changed what, newest first","tags":["Account"],"description":"Requires role: viewer.","parameters":[{"name":"limit","in":"query","required":false,"description":"1-1000, default 100","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/users":{"get":{"summary":"People and roles","tags":["Account"],"description":"Requires role: admin.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}}}}