Contents

API reference / Alerts

Update an alert

PATCH /api/v1/alerts/{alert}

update_alert Write MCP tool

Send only what changes. filters replaces the whole filter set.

A full-access key (ss_sk_…), or an editor or owner signed in.

Parameters

NameTypeDescription
alert required
path
string The alert's id.

Request body

JSON, sent with Content-Type: application/json.

NameTypeDescription
kind 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 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 string
One of: email slack discord teams
target 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 PATCH "https://sniffington.com/api/v1/alerts/{alert}" \
  -H "Authorization: Bearer $SCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"digest","spike":{"metric":"volume","multiple":1.5}}'