Sniffington API
Read and manage brand mentions over HTTP or MCP.
Overview
Sniffington finds public posts that mention your brand or keywords on Reddit, X, Hacker News, YouTube, TikTok and other platforms. An AI model drops the noise and tags each post with a sentiment and a category. This API reads and changes the same data you see in the app.
Base URL: https://sniffington.com/api/v1. Requests and responses are JSON. The OpenAPI 3.1 spec is at /openapi.json, and AI agents can start from /llms.txt.
Authentication
Create an API key in the app under Integrations → API keys, then send it as a bearer token with every request:
Authorization: Bearer ss_sk_…
ss_sk_…keys have full access and can read and write.ss_ro_…keys are read-only. A write with one returns 403.- Workspaces stored in the EU have keys that start
ss_sk_eu_…andss_ro_eu_…. They work the same way.
A key belongs to one workspace, so requests never name a workspace. The app shows a key only once. If one leaks, revoke it there and create a new one.
MCP clients such as ChatGPT and Claude can sign in with OAuth instead of using a key (see MCP). A few operations, such as creating API keys, need a workspace owner signed in to the app. The reference marks those Owner.
Agent sign-up
An AI agent can start its own account. A person still owns it: they approve once, by email, and the agent collects an API key. There's no password and no browser step for the agent.
1. The agent asks for an account for a person's email address:
curl -X POST https://sniffington.com/api/agent/signup -H "content-type: application/json" \
-d '{"email":"you@example.com","agent_name":"Claude","scope":"full"}'
scope is read or full (default full). region is us or eu; leave it out and it follows where the request comes from. The reply is 202 with a claim_id, a poll_secret and a poll_url.
2. The person gets an email with a link. They sign in with that address and choose the workspace, whether the agent may change things, and a daily budget. The link works for an hour, and only for the owner of that address.
3. The agent polls until the person has answered:
curl https://sniffington.com/api/agent/signup/<claim_id> -H "Authorization: Bearer <poll_secret>"
- 202
pending: keep waiting, a few seconds apart. - 200
approved: the body hasapi_key, shown once, plus the workspace,scopeanddaily_budget. Store the key now. - 403
denied: the person said no. 410: the link expired or the key was already collected. Start again.
Keys made this way carry a daily budget of 10, 25 or 100 costly actions: create_project, create_keyword, scan_now, scan_project, sniff_brand and, on the hosted app, the outbound tools rank_posts, check_thread and sniff_market. Reads are unlimited. Past the budget a call returns 429 with the code key_budget, and the MCP tool whoami shows how many are left. Anyone can set the same cap on a key they create by passing daily_budget to create_api_key. The plan's own limits apply as well.
To move up a plan, an agent with a read and write key calls request_upgrade (POST /v1/billing/upgrade-link). It returns a payment link for the account owner to open. Nothing is charged until they pay, and the plan changes when Polar confirms it.
Sign-ups are limited to 3 a day per email address and 10 a day per IP address.
Quickstart
Keep the key in an environment variable:
export SCOUT_API_KEY=ss_sk_…
List your projects. Each has an id that other calls use:
curl https://sniffington.com/api/v1/projects \
-H "Authorization: Bearer $SCOUT_API_KEY"
Add a keyword to a project. Aliases count as the same keyword, and posts that contain an excluded term are skipped:
curl -X POST https://sniffington.com/api/v1/projects/acme/keywords \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"term": "acme", "aliases": ["acme.com", "@acmehq"], "excluded": ["acme corp"]}'
List negative mentions from Reddit and X that nobody has handled yet, 50 at a time:
curl "https://sniffington.com/api/v1/mentions?project=acme&sources=reddit,x&sentiment=negative&status=open&limit=50" \
-H "Authorization: Bearer $SCOUT_API_KEY"
Mark one as done, using the id from that list:
curl -X PATCH "https://sniffington.com/api/v1/mentions/MENTION_ID" \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "done"}'
The API reference lists every operation with its parameters.
Pagination
List operations return one page of results and a cursor for the next:
{ "data": [ … ], "next_cursor": "WzE3NTg…", "total": 1234 }
Pass next_cursor back as cursor to get the next page. It is null on the last page. limit sets the page size: 25 by default, 100 at most. A cursor marks a position in the list, so posts that arrive while you page don't shift or repeat results.
Errors
Every error has the same shape. code is stable, so branch on it. message is written for people and may change.
{ "error": { "code": "not_found", "message": "no project acme" } }
| Status | Code | When |
|---|---|---|
| 400 | bad_request, validation_error | A parameter or field is missing or has the wrong type. The message names it. |
| 401 | unauthorized | No credentials, or the key is wrong, expired or revoked. |
| 402 | plan_limit | The plan's limit on projects, keywords or seats is reached. |
| 403 | forbidden | The credential isn't allowed to do this, for example a read-only key trying to write. |
| 404 | not_found | Nothing with that id in this workspace. |
| 409 | conflict | The request clashes with the current state, for example a name that's already taken. |
| 415 | unsupported_media_type | A write from a signed-in browser that isn't JSON. |
| 429 | rate_limited | Too many requests. Wait for the number of seconds in Retry-After. |
| 429 | daily_limit, metered_budget | The plan's daily limit on ranking, thread checks or market sniffs is used (resets at midnight UTC), or the month's metered calls are spent. |
A 5xx status means the server failed. Reads are safe to retry.
Rate limits
Each credential can make 240 reads (GET) and 60 writes per minute. Calls without a key, such as the public dashboard endpoints, are counted per IP address.
Past the limit you get a 429 with the code rate_limited. Wait a minute and try again.
Alerts
An alert sends a daily digest, or an instant message when a mention passes the urgency you set, by email, to Slack or to Discord. For Slack, paste an incoming webhook URL (https://hooks.slack.com/services/…) when you create the alert; for Discord, a Discord webhook URL. Create, test and delete alerts in the app or with the alert operations.
Finding people to reach (outbound)
Four operations help you find the people who need what a company sells, in the conversations where they're asking. They are API operations and MCP tools of the same name, and sniffington rank, thread, market in the CLI. They work on any company, tracked or not, and nothing is ever posted for you.
sniff_market(POST /v1/market/sniff): reads the company's website, then what Reddit, Hacker News and Bluesky said about it, its competitors and its category. Start here.rank_posts(POST /v1/posts/rank): send posts from there, or from X, LinkedIn or your own list, with the company and what it sells. Each comes back withp(the probability it is worth writing to its author, from the ranking model; null until one is trained),fitandkindfrom Jev, best first.check_thread(POST /v1/threads/check): for a post's URL, who has already commented and whether the brand or its people answered. Reddit, Hacker News and Bluesky are free; X and LinkedIn go through treg and count against the plan's metered calls.review_posts(POST /v1/posts/review): the AI reviewer proposes Good or Not relevant for each post with a one-line reason; see Review. It counts against the plan's reviewed posts a day.
A typical run: sniff_market for the company, rank_posts on the threads it returns (plus any you collected elsewhere), check_thread on the best few, then write to the ones nobody has answered.
Each operation has a daily limit per workspace, sized for what it costs us. Past it you get a 429 with the code daily_limit; the limit resets at midnight UTC. On a key with a daily_budget, each call also counts as one costly action.
| Plan | Posts ranked a day | Market sniffs a day | Thread checks a day |
|---|---|---|---|
| Free | 80 | 3 | 20 |
| Founder | 500 | 10 | 200 |
| Portfolio | 2,000 | 40 | 1,000 |
| Agency | 5,000 | 100 | 3,000 |
The typed signal
Every kept mention carries a signal object, the same for every use of Sniffington (a founder, an agency, a product team, developer relations, an outbound team): what the author is doing, how strong a lead it is, who it is for and the context around it. list_mentions and get_mention return it; the feed shows it as a small chip with the explanation.
type:asking,comparing,switching,complaint,praise,bug_report,feature_request,question,news,promo,other. One typed question to the decision model, asked with the relevance question. A post the AI check has not reached yet hastype: nullandtyped: false.strength: 0 to 1, how worth acting on. It is the ranking model's probability (strength_basis: "model") once one is trained, and Jev's fit reading divided by 100 until then ("fit"). 0.6 and over is a strong match.fitandfit_kind(buyer, user, pain, unrelated) are the reading it was built from.subjectandrole: the brand the post is for (a project: your brand, a client's brand, an account) and what it matched, and how the two relate:the subject,a rival of the subjectorthe category.context:age_days,window_daysandfresh;platform,place;author(kind person, company or bot, followers, account age and the other facts a platform sent);answered_by_subjectandnamed_by_others.explanationandreasons: a plain-words line and its codes, built from fixed phrases. No sentence a model wrote is stored.
A signal stays worth acting on for a window that depends on its type: asking 7 days, comparing 14 days, switching 7 days, complaint 14 days, praise 14 days, bug_report 14 days, feature_request 14 days, question 14 days, news 14 days, promo 14 days, other 14 days. Only kept posts inside the longest window are typed and scored in the background.
| Type | What the author is doing |
|---|---|
| asking | Asks for a tool, product or service to do a job, or for a recommendation: 'what do you use for X', 'any good tool for Y', 'looking for something that does Z'. |
| comparing | Weighs named products or approaches against each other, or asks which of them is better, and does not say they are leaving one. |
| switching | Is leaving a product, has just left one or is about to, or asks for an alternative to a named product: 'moving off X', 'X got too expensive, what else is there'. |
| complaint | Criticises a product, service or company, or tells of a bad experience with it, without asking anyone to fix a defect. |
| praise | Recommends, thanks or compliments a product, service or company they use. |
| bug_report | Reports that something is broken or behaves wrongly: an error, a crash, an outage, data lost, a defect that needs fixing. |
| feature_request | Wishes a product did something it does not do, or asks for a feature to be added. |
| question | Asks a question about a category or how to do something (how it works, how to set it up, which approach) without asking for a product recommendation. |
| news | Reports or discusses news: a launch, an update, funding, an acquisition, an article, a press piece or an announcement. |
| promo | Promotes something: an ad, the maker's own launch or pitch, a link drop, a giveaway, a job ad, an affiliate post. |
| other | None of these: chatter, a joke, a passing mention, an opinion on something else. |
answered_by_subject and named_by_others are null until someone has read the thread: no platform is called to show a feed. Call check_thread with the mention_id and the answer is kept on the mention with the time of the check (context.thread.checked_at). The one thing known without reading the thread is a reply this workspace sent through its own connected account, which sets answered_by_subject to true with the source reply_log.
Ask for the people choosing a tool this week, strongest first:
curl "https://sniffington.com/api/v1/mentions?signal_type=asking,switching&min_strength=0.6&max_age_days=7" \
-H "Authorization: Bearer $SCOUT_API_KEY"Playbooks: one engine, many uses
Every post is found, judged and ranked the same way for everyone. A playbook is the part that differs by use: which kinds of post count and how much, how fresh a post must be, how high the bar for "ready" sits, how the list is grouped, and what a person can do next. It is data, not code. Five are built in, a workspace can copy one and edit the copy, and get_brief turns the one in use into a ranked list of what is ready.
list_playbooksandget_playbookread them.apply_playbookpicks one for the workspace; nothing else changes and nothing is sent anywhere.create_playbook(withfromset to an id) copies one,update_playbookanddelete_playbookchange your own copies. Every value is checked and a wrong one is refused with the field named.get_briefwith a playbook applied returnsready: each item has thequote, theurl,age, ascoreandwhy_ready(plain words built from the post's typed signal), and thenext_actionsthat are available. Where the playbook groups,groupscarries one group per client, or per rival or topic and kind of post (so what keeps coming up shows as a count).countssays how many posts were considered, how many are ready, how many are still waiting for the AI to read or score them, and why the rest were left out. Passplaybookto try another without applying it.- The brief is computed from stored signal data on every view. No model is called, so it costs nothing and counts against no daily limit.
- A post is ready when its score, strength times the weight of its kind (
signal_weights) times the weight of whom it is about (roles: the subject, a rival or the category), reachesready_threshold, it is inside its window (windows, 1 to 14 days per kind), it was not written by a bot, and, where the playbook says so, nobody from the brand answered the thread (answered) and a person wrote it (authors).subject_onlylists the kinds that count only when the post is about the subject itself.
| Playbook | Subject | Ready from | Posts by | Groups |
|---|---|---|---|---|
Founders (founders) | own brand | 0.3 | people and companies | one list |
Agencies (agencies) | client brands | 0.3 | people and companies | by client |
Product marketers (product-marketers) | category | 0.35 | people | by what recurs |
Developer relations (developer-relations) | own brand | 0.3 | people and companies | one list |
GTM / outbound teams (gtm) | target accounts | 0.55 | people | one list |
Subject kinds: own_brand, client_brands, target_accounts, portfolio, category. For every kind but target_accounts the subject is a project (a brand with its keywords, rivals and topics). target_accounts is the workspace's imported accounts (Target accounts): the GTM brief lists the people to write to, one per person, each naming the account it is for.
Next actions that leave Sniffington (outreach, a GitHub issue, handing a lead to an outbound tool) are listed on a playbook as not available yet, stay out of the brief, and will need an approval when they arrive. The ones available now only read or change the workspace's own data, or save a reply draft for a person to post.
Kinds of post, in words: people asking for a tool or a recommendation; people comparing products; people leaving a product or looking for an alternative; complaints; praise; bug reports; feature requests; questions about the category; news and announcements; promotion and ads; anything else.
curl -X POST https://sniffington.com/api/v1/playbooks/gtm/apply \
-H "Authorization: Bearer $SCOUT_API_KEY"
curl "https://sniffington.com/api/v1/brief" \
-H "Authorization: Bearer $SCOUT_API_KEY"Target accounts: who to write to
An account is a company you want to write to: its domain, name, a one-liner, the lists it came from (a YC batch, a VC portfolio, a CSV), its competitors, the phrases people use to look for what it sells, and a status. Import a list, and Sniffington listens for the people asking, switching or complaining in each company's market, ranks what it finds, and the GTM playbook turns it into a list of people to write to this week, each with the quote, the link and why now. Nothing is sent to anyone.
import_accountsadds companies fromaccounts(domains or records),csv(CSV, TSV or JSON text, with or without a header row) orurl(a public list). 100 accounts a call; for a longer list sendcsvorurlagain withoffsetset to the previousnext_offset. The domain is the key, so importing the same list again changes nothing. Adddry_run: trueto write nothing and get what the import and a first scan would cost in model spend first.- In the background, each account's site is read once (what it sells, up to three competitors, the phrases people use to look for it), a typed question to the decision model says whether it looks like a business that buys software or a hobby, student or consumer project, and Reddit (with the comments under matching threads), Hacker News and Bluesky are scanned for the company's name, its competitors and those phrases. Posts from the last 14 days count; an ask or a switch stays worth acting on for 7.
- A post is judged once per account, whatever the number of scans: it is stored under a hash of its address, so a post collected again costs nothing. Bots, company accounts, news, ads and the company's own subreddit are ruled out first without a model. A hobby or consumer project's posts score lower, because on our own outreach data posts about them were worth writing about 37% of the time against 60% for YC and VC companies.
list_accountsshows the accounts with how many conversations are worth acting on now (filter byorigin,has_conversation,fresh_days,company_type),get_accountone account with its conversations ranked: the quote, the post it replies to, who wrote it, how it ranked and why.scan_accountasks for a fresh scan,update_accountchanges the competitors or phrases it listens for or pauses it,update_account_postmarks a conversation done, not relevant or (withverdict) good,delete_accountremoves it.check_threadtakes a conversation's id to see whether the company already answered it.get_briefwith thegtmplaybook applied lists the people to write to across all accounts, one per person, never one the company has already answered.
Reddit, Hacker News and Bluesky cost nothing to read. X and LinkedIn are paid per call, so they run only inside a monthly budget that the workspace owner sets in the app (off by default), at most weekly per account.
| Plan | Accounts | Posts judged a day for accounts |
|---|---|---|
| Free | 5 | 60 |
| Founder | 25 | 600 |
| Portfolio | 150 | 3,000 |
| Agency | 1,000 | 12,000 |
curl -X POST https://sniffington.com/api/v1/accounts/import \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"csv": "domain,name,origin\nacme.io,Acme,yc-fall-2026", "dry_run": true}'
curl -X POST https://sniffington.com/api/v1/playbooks/gtm/apply \
-H "Authorization: Bearer $SCOUT_API_KEY"
curl "https://sniffington.com/api/v1/brief" \
-H "Authorization: Bearer $SCOUT_API_KEY"Review: teaching Sniffington what is good
Two verdicts, per workspace: **Good** (worth acting on) and **Not relevant**. A person (or an agent acting for one) gives them with update_mention and update_account_post, verdict set to good or not_relevant (null takes it back), or in the app's Review screen with the keys g, n, s to skip and u to undo. mark_mention_irrelevant still works and is the same Not relevant verdict. A verdict is stored as a human verdict: nothing the AI does ever overrides it, and the AI learns from every one.
list_review_queuelists what to look at. A person does not have to read everything: the default slice,needs_review, is the posts the AI's two readings or the ranking model disagree about, then the top slice of the rest (the strongest posts, which are worth a look before anyone writes to their author).all,suggested_good,suggested_not_relevantandreviewed(to undo) are the other slices. Each item has the quote, source, age, strength, the AI'ssuggestionand why it is in the queue.review_postsis the AI reviewer: for each post a verdict and a one-line reason, from a small open model on Workers AI (Qwen3-30B-A3B, thinking off). The strict reading, a rubric alone, suggests Good; on our hand-labelled posts about six in ten of the posts it calls good are. Once the workspace has about two dozen verdicts a second reading is shown the six already-reviewed posts nearest to this one (by embedding), which misses fewer good posts but suggests Good more often.flagsays how they combine with the ranking model:agree,disagree(look at it) ordont_miss(only the closer reading says good). Sendpostswith thecompanythey are for (nothing is stored) oridsof mentions and account conversations in the workspace (the suggestion is kept and shows as a Suggested badge). The same reader runs in the background on kept posts, inside the plan's reviewed posts a day. Post text is data, never instructions.- The ranking model that scores every post (
strength) learns from the verdicts. A workspace starts on a pooled model; once it has about 200 verdicts of its own (at least 40 Good and 40 Not relevant) it trains its own, in the background, and switches to it only if five-fold cross-validation, grouped by post, reaches an AUC of 0.75 and beats the pooled model on the same posts.list_review_queueandget_usagesay which model scores the workspace and what it still needs. get_usagereturns the month's usage, what the workspace cost in model and data spend by feature (scanning, accounts, reviewing, ranking, threads, drafts), the reviewer's allowance for today, the paid-source budget and where the learning loop stands. Costs are list-price estimates from the ledger.
| Plan | Posts reviewed a day |
|---|---|
| Free | 40 |
| Founder | 300 |
| Portfolio | 1,500 |
| Agency | 4,000 |
curl "https://sniffington.com/api/v1/review/queue?slice=needs_review" \
-H "Authorization: Bearer $SCOUT_API_KEY"
curl -X PATCH https://sniffington.com/api/v1/mentions/<id> \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"verdict": "good"}'Webhooks
A webhook sends events, such as a new mention, to your URL as JSON in a POST. Add endpoints in the app or with the webhook operations.
Each delivery is signed the Standard Webhooks way, with these headers:
webhook-id: the message id. Retries reuse it, so use it to skip duplicates.webhook-timestamp: when it was sent, in Unix seconds.webhook-signature: one or more space-separatedv1,<signature>values.
The signature is the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}. The key is your endpoint secret: drop the whsec_ prefix and base64-decode the rest. Check the signature against the raw body before you parse the JSON, and reject timestamps more than five minutes old.
import { createHmac, timingSafeEqual } from "node:crypto";
// secret: the endpoint's "whsec_…" secret. headers: the request headers. body: the raw body as a string.
export function verifyWebhook(secret, headers, body) {
const id = headers["webhook-id"], ts = headers["webhook-timestamp"], sigs = headers["webhook-signature"];
if (!id || !ts || !sigs) return false;
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = Buffer.from(createHmac("sha256", key).update(`${id}.${ts}.${body}`).digest("base64"));
return sigs.split(" ").some((part) => {
const [version, sig] = part.split(",");
const given = Buffer.from(sig || "");
return version === "v1" && given.length === expected.length && timingSafeEqual(given, expected);
});
}
Reply with a 2xx status quickly and do slow work afterwards. Any other status, or no reply, counts as a failure, and the delivery is retried with growing gaps for about 90 hours.
MCP
Sniffington is also an MCP server, at https://sniffington.com/mcp over Streamable HTTP.
Personal assistants and team agents use the same endpoint. For Grokbot, Muse, Cursor and other clients, see the connection guide. Clients can use the initialize handshake or per-request discovery (server/discover); legacy SSE-only clients need a bridge.
- ChatGPT, Claude and other clients that support OAuth 2.1 with dynamic client registration only need that URL. They register themselves and ask you to sign in, so there's no key to copy.
- Clients without OAuth can send an API key as
Authorization: Bearer ss_…. With a read-only key, only the read tools work.
Each operation marked MCP tool in the reference is a tool with the same name, and takes that operation's parameters and body fields as arguments.
Claude Code:
claude mcp add --transport http sniffington https://sniffington.com/mcp
A client configured with a key:
{
"mcpServers": {
"sniffington": {
"url": "https://sniffington.com/mcp",
"headers": {
"Authorization": "Bearer ss_ro_…"
}
}
}
}