Contents

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_… and ss_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 has api_key, shown once, plus the workspace, scope and daily_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" } }
StatusCodeWhen
400bad_request, validation_errorA parameter or field is missing or has the wrong type. The message names it.
401unauthorizedNo credentials, or the key is wrong, expired or revoked.
402plan_limitThe plan's limit on projects, keywords or seats is reached.
403forbiddenThe credential isn't allowed to do this, for example a read-only key trying to write.
404not_foundNothing with that id in this workspace.
409conflictThe request clashes with the current state, for example a name that's already taken.
415unsupported_media_typeA write from a signed-in browser that isn't JSON.
429rate_limitedToo many requests. Wait for the number of seconds in Retry-After.
429daily_limit, metered_budgetThe 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 with p (the probability it is worth writing to its author, from the ranking model; null until one is trained), fit and kind from 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.

PlanPosts ranked a dayMarket sniffs a dayThread checks a day
Free80320
Founder50010200
Portfolio2,000401,000
Agency5,0001003,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 has type: null and typed: 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. fit and fit_kind (buyer, user, pain, unrelated) are the reading it was built from.
  • subject and role: 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 subject or the category.
  • context: age_days, window_days and fresh; platform, place; author (kind person, company or bot, followers, account age and the other facts a platform sent); answered_by_subject and named_by_others.
  • explanation and reasons: 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.

TypeWhat the author is doing
askingAsks 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'.
comparingWeighs named products or approaches against each other, or asks which of them is better, and does not say they are leaving one.
switchingIs 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'.
complaintCriticises a product, service or company, or tells of a bad experience with it, without asking anyone to fix a defect.
praiseRecommends, thanks or compliments a product, service or company they use.
bug_reportReports that something is broken or behaves wrongly: an error, a crash, an outage, data lost, a defect that needs fixing.
feature_requestWishes a product did something it does not do, or asks for a feature to be added.
questionAsks 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.
newsReports or discusses news: a launch, an update, funding, an acquisition, an article, a press piece or an announcement.
promoPromotes something: an ad, the maker's own launch or pitch, a link drop, a giveaway, a job ad, an affiliate post.
otherNone 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_playbooks and get_playbook read them. apply_playbook picks one for the workspace; nothing else changes and nothing is sent anywhere. create_playbook (with from set to an id) copies one, update_playbook and delete_playbook change your own copies. Every value is checked and a wrong one is refused with the field named.
  • get_brief with a playbook applied returns ready: each item has the quote, the url, age, a score and why_ready (plain words built from the post's typed signal), and the next_actions that are available. Where the playbook groups, groups carries one group per client, or per rival or topic and kind of post (so what keeps coming up shows as a count). counts says 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. Pass playbook to 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), reaches ready_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_only lists the kinds that count only when the post is about the subject itself.
PlaybookSubjectReady fromPosts byGroups
Founders (founders)own brand0.3people and companiesone list
Agencies (agencies)client brands0.3people and companiesby client
Product marketers (product-marketers)category0.35peopleby what recurs
Developer relations (developer-relations)own brand0.3people and companiesone list
GTM / outbound teams (gtm)target accounts0.55peopleone 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_accounts adds companies from accounts (domains or records), csv (CSV, TSV or JSON text, with or without a header row) or url (a public list). 100 accounts a call; for a longer list send csv or url again with offset set to the previous next_offset. The domain is the key, so importing the same list again changes nothing. Add dry_run: true to 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_accounts shows the accounts with how many conversations are worth acting on now (filter by origin, has_conversation, fresh_days, company_type), get_account one account with its conversations ranked: the quote, the post it replies to, who wrote it, how it ranked and why. scan_account asks for a fresh scan, update_account changes the competitors or phrases it listens for or pauses it, update_account_post marks a conversation done, not relevant or (with verdict) good, delete_account removes it. check_thread takes a conversation's id to see whether the company already answered it.
  • get_brief with the gtm playbook 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.

PlanAccountsPosts judged a day for accounts
Free560
Founder25600
Portfolio1503,000
Agency1,00012,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_queue lists 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_relevant and reviewed (to undo) are the other slices. Each item has the quote, source, age, strength, the AI's suggestion and why it is in the queue.
  • review_posts is 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. flag says how they combine with the ranking model: agree, disagree (look at it) or dont_miss (only the closer reading says good). Send posts with the company they are for (nothing is stored) or ids of 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_queue and get_usage say which model scores the workspace and what it still needs.
  • get_usage returns 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.
PlanPosts reviewed a day
Free40
Founder300
Portfolio1,500
Agency4,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-separated v1,<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_…"
      }
    }
  }
}