Contents

API reference / Mentions

Change the status of many mentions

POST /api/v1/mentions/bulk

bulk_update_mentions Write MCP tool

Sets the status of every mention matching the filters (the list_mentions query parameters), or of the given ids. Useful for clearing an old backlog, e.g. status=done with status filter open and until=90 days ago.

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

Parameters

NameTypeDescription
project
query
string Project id.
sources
query
array of string Sources to search. Omit for every source available.
One of: reddit linkedin x hn instagram github stackoverflow devto bluesky news youtube tiktok threads facebook appstore feeds jobs pages
sentiment
query
array of string Sentiment.
One of: positive negative neutral
status
query
array of string Workflow status.
One of: open done follow_up
relevance
query
array of string Urgency band (high ≥70, medium ≥40).
One of: high medium low
categories
query
array of integer Category ids.
keywords
query
array of integer Keyword ids.
groups
query
array of integer Keyword group ids.
authors
query
array of string Exact author handles, e.g. @someone or u/someone.
lang
query
array of string Only posts in these languages (two-letter codes such as en, de).
intent
query
array of string Posts about a competitor, by what the author is doing.
One of: complaint praise alternative pricing other
lead_min
query
integer
0–100
Only posts with a lead score of at least this (needs an ideal customer description on the project).
lead_status
query
array of string Only leads with this status.
One of: new contacted skip
urgency_min
query
integer
0–100
urgency_max
query
integer
0–100
tier
query
array of string How much a kept post is worth reading: priority (urgency 50+), read, or passing (urgency under 20 and the AI's note says nothing was said about it). Every kept post is in the default results; use this to look at one tier.
One of: priority read passing
hide_passing
query
boolean Leave out the passing mentions: posts that name the tracked word and say nothing worth acting on. Off by default.
author_kind
query
array of string Who wrote the post: a person, a company promoting itself, or a bot or spam account. unknown: nobody has said (older posts, and posts the chat model judged). Bots are ruled out, so they show under include=irrelevant or all.
One of: person company bot unknown
hide_bots
query
boolean Leave out posts by bot or spam accounts. Off by default.
hide_companies
query
boolean Leave out posts by company accounts promoting themselves. Off by default.
signal_type
query
array of string What the author is doing (the typed signal): asking for a tool or recommendation, comparing, switching (leaving a product or asking for an alternative), complaining, praising, reporting a bug, requesting a feature, asking a category question, news, promo, or other. Only kept posts the AI has typed; use signal_type=asking,switching to find people choosing a tool.
One of: asking comparing switching complaint praise bug_report feature_request question news promo other
min_strength
query
number
0–1
Only posts whose signal strength is at least this (0 to 1; 0.6 is a strong match). Strength is the ranking model's probability that the post is worth acting on; posts not scored yet are left out.
max_age_days
query
number
0–3650
Only posts written within this many days (by the post's own time, not when it was found).
fresh
query
boolean Only posts still inside their signal's window: asking 7 days, switching 7 days, every other type and untyped posts 14 days.
verdict
query
array of string What a person decided (the review queue): good, not_relevant, or unreviewed (nobody has ruled on it). Not relevant posts are out of the feed, so ask for them with include=all.
One of: good not_relevant unreviewed
suggested
query
array of string What the AI reviewer suggested: good, not_relevant, or disagree (its two readings or the ranking model disagree, so a person should look).
One of: good not_relevant disagree
min_engagement
query
integer
at least 0
engagement
query
string Per-source minimum engagement, e.g. x:10,reddit:5.
since
query
string ISO date/time or epoch ms.
until
query
string ISO date/time or epoch ms.
found_since
query
string Only mentions first collected at or after this ISO date/time or epoch ms, however old the post itself is.
q
query
string Full-text search over text, author, place and the AI's summary.
include
query
string relevant (default): real mentions. irrelevant: filtered out as namesakes or noise.
One of: relevant irrelevant all
range
query
string A relative date window; since/until win when both are given.
One of: today 7d 30d 90d 12m all
view
query
integer Apply a saved view's filters.

Request body

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

NameTypeDescription
status required string The new status.
One of: open done follow_up
ids array of string
up to 5000 items
Only these mention ids (max 5000).

Example

curl -X POST "https://sniffington.com/api/v1/mentions/bulk" \
  -H "Authorization: Bearer $SCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}'