How Snitch works

Concepts

Workspace

Your team and its billing. Everything else lives inside one.

Project

One thing you are watching — usually a product. Holds its own keywords, categories and alerts.

Keyword group

Which of three questions a keyword answers: is this about us, about a competitor, or is this someone describing a problem we solve? The group decides which question the classifier is asked, so a keyword in the wrong group is not mislabelled — its matches are discarded.

Keyword

A phrase Snitch searches for, inside one group. A competitor keyword also carries a line describing that competitor, so the classifier is not told the subject is you.

Mention

One public post, comment or video description that matched a keyword. Duplicates of the same post are collapsed into one.

Agent action

Something Snitch proposes — a reply, or a Linear issue. It stays proposed until a person approves it.

Quickstart

1. Say what you are. One sentence on the keywords page. Without it, “this pasta is wonderful” and a post about your product look identical.
2. Add a keyword to each group. Your product name under My brand, two or three rivals under Competitors, and a phrase your customers would use about their problem under Customers. That last one finds people who have never heard of you.
3. Let a collection run finish. Snitch searches each source and stores what matches. You can force one from the dashboard or with POST /api/v1/scans.
4. Read the queue. Each mention arrives with a category, an urgency score, and a badge for the group that found it. Filter the feed to one group, or point an alert at one, to answer a single question at a time.
5. Approve a reply. Snitch drafts it. Nothing is posted until you approve, and every approval records who and when.

Sources

Snitch only reads what is publicly visible. It does not read private messages, private groups, or anything behind a login.

Approvals

Snitch never posts on its own. A drafted reply is an agent action in the proposed state. Approving it moves it to approved, then executing, then completed. Rejecting it stops there. Failures land in failed with the reason attached.

A mention itself moves through its own statuses:

new

Collected and categorised, not yet looked at.

reviewing

Someone on the team has it open.

actioned

A reply was approved, or an issue was created.

saved

Kept for later without acting on it.

ignored

Dismissed. Stays out of counts and alerts.

archived

Removed from the working queue.

REST API

Authenticate with a workspace API key as a bearer token. Keys start with sn_, are stored only as a SHA-256 hash, and carry scopes such as mentions:read or keywords:write. Create one under Developer in the dashboard.

curl https://heysnitch.com/api/v1/mentions?projectId=PROJECT_ID \
  -H "Authorization: Bearer sn_your_key_here"

MCP server

Point any MCP client at https://heysnitch.com/mcp and authenticate with the same bearer token. The server speaks JSON-RPC over HTTP POST and implements protocol version 2025-06-18. The tools are the same capabilities the dashboard uses, so nothing extra needs building.

curl -X POST https://heysnitch.com/mcp \
  -H "Authorization: Bearer sn_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

35 tools are exposed. Read-only tools are annotated as such, and the destructive ones are flagged so a client can ask before running them.

• list_projectsprojects:read
• get_projectprojects:read
• create_projectprojects:write
• update_projectprojects:write
• archive_projectprojects:writedestructive
• list_keyword_groupskeywords:read
• create_keyword_groupkeywords:write
• update_keyword_groupkeywords:write
• delete_keyword_groupkeywords:writedestructive
• list_keywordskeywords:read
• create_keywordkeywords:write
• update_keywordkeywords:write
• list_rejectedmentions:read
• delete_keywordkeywords:writedestructive
• list_mentionsmentions:read
• get_mentionmentions:read
• update_mention_statusmentions:write
• list_draftsdrafts:read
• create_draftdrafts:write
• update_draftdrafts:write
• list_categoriescategories:read
• create_categorycategories:write
• update_categorycategories:write
• delete_categorycategories:writedestructive
• list_saved_viewsviews:read
• create_saved_viewviews:write
• delete_saved_viewviews:writedestructive
• post_draftreplies:publish
• list_postsreplies:read
• retract_postreplies:publishdestructive
• list_source_accountsaccounts:read
• disconnect_source_accountaccounts:writedestructive
• list_audit_eventsaudit:read
• get_mention_analyticsanalytics:read
• get_usageusage:read

Webhooks

Register an endpoint and Snitch will POST events to it as they happen. Each delivery carries three headers: webhook-id, webhook-timestamp and webhook-signature.

The signature is v1, followed by a base64 HMAC-SHA256 of {id}.{timestamp}.{body}, signed with your endpoint secret. Verify it before trusting a payload, and reject timestamps that are far from now.

A delivery that does not return a 2xx is retried up to eight times with exponential backoff starting at one minute. Redirects are not followed.

Plans and limits

When you hit the monthly limit Snitch pauses collection until the next period. You are never charged an overage, nothing is deleted, and the feed resumes on its own.

API and MCP calls are rate limited by class: read, write, and expensive for calls that trigger collection or analytics.