Create an alert
POST /api/v1/alerts
Email, Slack or Discord. Each workspace can send 30 alert emails and 200 Slack or Discord messages a day, and have up to 200 alerts.
A full-access key (ss_sk_…), or an editor or owner signed in.
Request body
JSON, sent with Content-Type: application/json.
| Name | Type | Description |
|---|---|---|
kind required |
string | digest: one message on a schedule (see `frequency`). rule: a message the moment a matching mention arrives. report: a branded weekly report on one brand, by email, for a client (project_id required; set the look under the workspace branding). competitors: a weekly summary of each competitor's judged posts with the posts behind it (weekly by default; see `frequency`). spike: one message when volume (or negative mentions) runs well above normal, see `spike`. brief: the playbook's ready list with its quotes, links and drafts, on a schedule (daily or weekly); nothing ready, nothing sent. ready: one message for each post the moment it enters the playbook's ready list (use a project_id for a client). viral: one message when a complaint about the brand arrives already popular (filters.min_engagement, default 50) and nobody from the brand has answered. A brief, ready or viral alert made by an agent is created turned off with a proposal in the approval queue (list_actions); a person turns it on. One of: digest rule spike competitors report brief ready viral |
spike |
object or null | Spike alerts: compares the last `window_hours` with the average window of the previous seven days. |
spike.metric |
string | volume: every matching mention. negative: only negative-sentiment ones (a crisis). Default volume. One of: volume negative |
spike.multiple |
number 1.5–50 |
Fire at this many times the usual. Default 3. |
spike.min_count |
integer 3–1000 |
And at least this many in the window, so a quiet brand never fires on noise. Default 10. |
spike.window_hours |
integer | The window to measure. Default 6. One of: 1 3 6 12 24 |
frequency |
string | Digest only: hourly (when there is something new), daily at `hour` (default) or weekly at `hour` on `weekday`. One of: hourly daily weekly |
weekday |
integer or null 0–6 |
Weekly digest: 0 = Sunday … 6 = Saturday, in `timezone` (default 1, Monday). |
name required |
string 1–80 characters |
Shown in the app and in each message. |
enabled |
boolean | |
project_id |
string or null | The project to watch; null for every project. |
channel required |
string | One of: email slack discord teams |
target required |
string up to 500 characters |
email: an address. slack: a channel ID or #name. discord: a webhook URL (https://discord.com/api/webhooks/…). teams: the URL of a Teams Workflows webhook. |
hour |
integer or null 0–23 |
Digest: the local hour to send, 0–23. |
timezone |
string or null | IANA timezone for `hour`, e.g. America/New_York. Defaults to the workspace's. |
filters |
object | Only mentions matching every filter set here. Leave a filter out to match everything. |
filters.sources |
array of string | Only these sources. One of: reddit linkedin x hn instagram github stackoverflow devto bluesky news youtube tiktok threads facebook appstore feeds jobs pages |
filters.sentiment |
array of string | Only these sentiments. One of: positive negative neutral |
filters.categories |
array of integer | Only these category ids. |
filters.groups |
array of integer | Only these keyword group ids. |
filters.keywords |
array of integer | Only these keyword ids. |
filters.authors |
array of string up to 50 items |
Only these authors: exact handles, any case, e.g. @someone or u/someone. |
filters.min_engagement |
integer at least 0 |
Only posts with at least this much engagement. A viral alert fires at this many (default 50). |
filters.playbook |
string | Brief alerts: the playbook whose brief is sent (default: the workspace's). |
min_urgency |
integer or null 0–100 |
Only mentions at or above this urgency (0–100). |
min_lead_score |
integer or null 0–100 |
Only mentions at or above this lead score (0–100). Needs an ideal customer description on the project, which is what scores a post. |
Returns
Alert
Example
curl -X POST "https://sniffington.com/api/v1/alerts" \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind":"digest","name":"Acme","channel":"email","target":"…"}'