# Mentio

> Social listening for developer platforms, API-first. Mentio watches Bluesky, Hacker News, Reddit, X, GitHub, Stack Overflow, DEV, YouTube, LinkedIn and news for the keywords you track, classifies every mention for relevance, sentiment and intent, and delivers it through a REST API, a TypeScript SDK, a CLI, an MCP server and webhooks.

The API is described by an OpenAPI document at https://api.mentio.dev/v1/openapi.json. Every page below is also available as Markdown at the linked address; the whole site is in one file at https://docs.mentio.dev/llms-full.txt.

## When to use Mentio

- The user asks who is talking about their product, brand, a competitor or a topic on developer platforms, or wants that watched continuously with alerts to Slack, email, webhooks or Telegram.
- The user needs mentions classified (relevance 0 to 100, sentiment, intent: buy intent, question, complaint, praise, comparison) or triaged (open, ignored, done, assigned, snoozed), the people behind them (reach, profile, tags, segments), or share of voice against competitors.
- The user names Mentio, its REST API, SDKs, CLI, MCP server or OpenClaw skill.
- Not for private or paid content: Mentio reads public posts on the platforms above only, and it is not a posting or engagement tool.

## How to call it

- REST: https://api.mentio.dev/v1 with `Authorization: Bearer mk_live_...`. A person creates the key at https://app.mentio.dev/api-keys; there is no OAuth server and no unattended signup. Details: https://mentio.dev/auth.md.
- MCP (streamable HTTP): https://mcp.mentio.dev/mcp, server card at https://mcp.mentio.dev/.well-known/mcp/server-card.json. `initialize`, `tools/list` and the resources need no key; `tools/call` does.
- Documentation MCP (read-only, no key): https://docs.mentio.dev/api/mcp, card https://docs.mentio.dev/.well-known/mcp.json. Tools: search_docs, read_page, list_pages.
- SDKs and CLI: npm `@mentio-dev/sdk`, PyPI `mentio`, `npx @mentio-dev/cli`. Skill for agents: https://mentio.dev/.well-known/agent-skills/mentio/SKILL.md.
- Versioning: the API lives under `/v1`; additive changes never break a client, and a breaking change would ship as a new path with Deprecation and Sunset headers on the old one (https://docs.mentio.dev/conventions.mdx).
- Changelog: https://docs.mentio.dev/changelog (Markdown at https://docs.mentio.dev/changelog.mdx, RSS at https://docs.mentio.dev/changelog/rss.xml), newest first, one entry per user-facing change.

## Guides

- [Overview](https://docs.mentio.dev/index.mdx): What Mentio is, how a mention travels from a platform to your inbox, and the five ways to build on it.
- [Alerts and channels](https://docs.mentio.dev/alerts.mdx): Rules decide what you hear about and when. Channels are where it lands.
- [Slack integration](https://docs.mentio.dev/alerts/slack.mdx): Connect a workspace and get relevant mentions posted to a channel.
- [Telegram integration](https://docs.mentio.dev/alerts/telegram.mdx): Get mention alerts and daily digests in a Telegram chat or group.
- [Authentication](https://docs.mentio.dev/authentication.mdx): Bearer API keys, scopes, and key management.
- [Billing](https://docs.mentio.dev/billing.mdx): The prepaid balance, what a keyword-day and a mention cost, and the wallet and ledger endpoints.
- [CLI](https://docs.mentio.dev/cli.mdx): Every endpoint as a mentio command, plus a live feed and MCP setup, for scripts and terminals.
- [Account commands](https://docs.mentio.dev/cli/account.mdx): Who you are, keys, the company profile, usage, the team, the stored login, MCP setup and a health check.
- [Alerts and channels commands](https://docs.mentio.dev/cli/alerts.mdx): Rules that decide what you hear about, and the channels it lands in.
- [Analytics commands](https://docs.mentio.dev/cli/analytics.mdx): The four reports over one window: summary, series, breakdown, share of voice.
- [Keywords commands](https://docs.mentio.dev/cli/keywords.mdx): Track, tune, mute and remove the terms Mentio watches.
- [Mentions commands](https://docs.mentio.dev/cli/mentions.mdx): Search, read, triage and export mentions, and follow the feed live.
- [People and segments commands](https://docs.mentio.dev/cli/people.mdx): The authors behind the mentions, your annotations on them, and saved segments.
- [Conventions](https://docs.mentio.dev/conventions.mdx): The rules every endpoint follows, so one resource teaches you all of them.
- [Errors](https://docs.mentio.dev/errors.mdx): The error envelope and every stable error code.
- [How it works](https://docs.mentio.dev/how-it-works.mdx): The ingestion pipeline, per-platform freshness, and the mention lifecycle.
- [OpenClaw](https://docs.mentio.dev/integrations/openclaw.mdx): Install the Mentio skill from ClawHub so OpenClaw tracks keywords, searches and triages mentions, sets up alerts and reads analytics from natural language.
- [MCP server](https://docs.mentio.dev/mcp.mdx): Connect Claude Code, Cursor, Codex, Gemini, VS Code and any MCP client to your mention feed.
- [Tools](https://docs.mentio.dev/mcp/tools.mdx): Every tool the MCP server exposes, by area.
- [Quickstart](https://docs.mentio.dev/quickstart.mdx): A keyword, the company profile, a search and a triage in five calls.
- [SDKs](https://docs.mentio.dev/sdks.mdx): Typed clients for the Mentio API, generated from its OpenAPI document. TypeScript and Python are published; any other language is a generator run away.
- [Python](https://docs.mentio.dev/sdks/python.mdx): The mentio package, one call per endpoint, sync and async.
- [TypeScript](https://docs.mentio.dev/sdks/typescript.mdx): The @mentio-dev/sdk package, one typed function per endpoint.
- [Webhooks](https://docs.mentio.dev/webhooks.mdx): How deliveries work: the flow, retries, idempotency, signature verification, and the events you can receive.
- [Digest events](https://docs.mentio.dev/webhooks/digest-events.mdx): What a daily rule sends once a day.
- [Mention events](https://docs.mentio.dev/webhooks/mention-events.mdx): What an instant rule sends for every matching mention.

## API reference

- [Introduction](https://docs.mentio.dev/api.mdx): Every Mentio endpoint, generated from the live OpenAPI spec.
- [Create an alert](https://docs.mentio.dev/api/alerts/create-alert.mdx): A rule (what to watch, the filter) times channels. mode instant sends each matching mention as it happens; daily sends one digest at schedule.hour in schedule.timezone; weekly sends one a week on schedule.weekday (0 Sunday to 6 Saturday).
- [Create a channel](https://docs.mentio.dev/api/alerts/create-channel.mdx)
- [Delete an alert](https://docs.mentio.dev/api/alerts/delete-alert.mdx)
- [Delete a channel](https://docs.mentio.dev/api/alerts/delete-channel.mdx)
- [Get an alert](https://docs.mentio.dev/api/alerts/get-alert.mdx)
- [Get a channel](https://docs.mentio.dev/api/alerts/get-channel.mdx)
- [List alerts](https://docs.mentio.dev/api/alerts/list-alerts.mdx)
- [List deliveries to a channel](https://docs.mentio.dev/api/alerts/list-channel-deliveries.mdx)
- [List channels](https://docs.mentio.dev/api/alerts/list-channels.mdx)
- [Mute authors on an alert](https://docs.mentio.dev/api/alerts/mute-alert-authors.mdx): Add authors to the alert's muted list without touching the rest of its filter. Links are read the way the dashboard reads them: a post link mutes its author, twitter.com becomes x.com, a Hacker News profile keeps its id. Authors already muted are skipped, so a retry is safe. An entry that names no person (a subreddit, a story) rejects the request with that entry named.
- [Rotate a webhook secret](https://docs.mentio.dev/api/alerts/rotate-webhook-secret.mdx)
- [Send a digest now](https://docs.mentio.dev/api/alerts/run-alert-digest.mdx)
- [Send a test through an alert's channels](https://docs.mentio.dev/api/alerts/test-alert.mdx)
- [Send a test to a channel](https://docs.mentio.dev/api/alerts/test-channel.mdx)
- [Unmute authors on an alert](https://docs.mentio.dev/api/alerts/unmute-alert-authors.mdx): Remove authors from the alert's muted list without touching the rest of its filter. Name each one by the stored entry or by any link to that profile or its posts. Authors that are not muted are ignored, so a retry is safe.
- [Update an alert](https://docs.mentio.dev/api/alerts/update-alert.mdx)
- [Update a channel](https://docs.mentio.dev/api/alerts/update-channel.mdx)
- [Mentions grouped by one dimension](https://docs.mentio.dev/api/analytics/get-analytics-breakdown.mdx): One table of matched, relevant and sentiment counts grouped by `by`: platform, keyword, sentiment, intent, status, hour (weekday and hour of day) or person. The window is `range` (7d, 30d, 90d, 365d, ending today) or `from` and `to`, cut into days in `timezone` (UTC by default); `keywordIds` and `platforms` narrow it; `compare=true` adds the period of the same length right before it. Time axis is the publish date.
- [Mentions over time](https://docs.mentio.dev/api/analytics/get-analytics-series.mdx): Matched, relevant and sentiment counts per day or week across the window, as one total series or split per platform or per keyword with `by`. The window is `range` (7d, 30d, 90d, 365d, ending today) or `from` and `to`, cut into days in `timezone` (UTC by default); `keywordIds` and `platforms` narrow it; `compare=true` adds the period of the same length right before it. Time axis is the publish date.
- [Headline counts for a window](https://docs.mentio.dev/api/analytics/get-analytics-summary.mdx): Matched and relevant mentions, distinct posts and people, sentiment, buying intent and questions, estimated reach, and where the matches stand in triage. The window is `range` (7d, 30d, 90d, 365d, ending today) or `from` and `to`, cut into days in `timezone` (UTC by default); `keywordIds` and `platforms` narrow it; `compare=true` adds the period of the same length right before it. Time axis is the publish date.
- [Brand against competitors](https://docs.mentio.dev/api/analytics/get-share-of-voice.mdx): Every keyword matched in the window with its counts and its share of brand plus competitor matches; topic keywords are counted but stay out of the split. The window is `range` (7d, 30d, 90d, 365d, ending today) or `from` and `to`, cut into days in `timezone` (UTC by default); `keywordIds` and `platforms` narrow it; `compare=true` adds the period of the same length right before it. Time axis is the publish date.
- [Create an API key](https://docs.mentio.dev/api/api-keys/create-api-key.mdx): Mint a key for this workspace. The key itself is returned once; only its hash is stored. `expiresAt` makes it stop working at an instant (a key for a contractor or a one-off script); it stays listed until revoked.
- [List API keys](https://docs.mentio.dev/api/api-keys/list-api-keys.mdx)
- [Revoke an API key](https://docs.mentio.dev/api/api-keys/revoke-api-key.mdx): Takes effect at once on the API and within a few minutes on cached verifications.
- [Introspect the credential](https://docs.mentio.dev/api/auth/whoami.mdx): The workspace this credential acts on, how the request authenticated (an API key, an OAuth access token from an MCP sign-in, or the dashboard session), whether it may write, and for a key its id and expiry. Run it first: a read key answers 403 read_only_key on every write, and a wrong workspace is the classic scripting mistake.
- [Get the company profile](https://docs.mentio.dev/api/company/get-company.mdx): What the classifier knows about you: name, description, use cases, your own accounts, and the composed context it reads.
- [Update the company profile](https://docs.mentio.dev/api/company/update-company.mdx): Changing profile fields recomposes the classifier context; setting `context` directly overrides it until the next profile edit. Relevance scores for new mentions follow at once.
- [Get the workspace filters](https://docs.mentio.dev/api/filters/get-filters.mdx): The noise rules applied to every keyword before a mention is stored: excluded terms and authors, excluded GitHub repositories, and the subreddits Reddit posts may (or may not) come from. A post they reject is never classified, delivered or billed. Keyword-level rules live on each keyword (`matching`); both apply.
- [Update the workspace filters](https://docs.mentio.dev/api/filters/update-filters.mdx): Replace any of the lists; an omitted list is untouched and an empty one clears it. Entries are stored in canonical form (terms lowercased, authors as profile links or bare names, repositories as owner/name, subreddits without r/). Takes effect on new mentions within a minute; stored mentions are untouched.
- [Track a keyword](https://docs.mentio.dev/api/keywords/create-keyword.mdx): Start tracking a word or phrase. Matching, classification and delivery begin on the next poll. A funded workspace tracks up to 500 keywords; each costs $5 per month, deducted daily from the balance. `matching` narrows what the term matches (required and excluded terms, excluded authors, case) before a mention is stored, so a rejected post is never billed; `context` is a sentence the classifier reads for this keyword only.
- [Delete a keyword](https://docs.mentio.dev/api/keywords/delete-keyword.mdx): Removes the keyword and its matches. Posts also matched by another keyword stay.
- [Get a keyword](https://docs.mentio.dev/api/keywords/get-keyword.mdx)
- [List keywords](https://docs.mentio.dev/api/keywords/list-keywords.mdx): Every keyword of the workspace, newest first, with its match stats and poll health.
- [Update a keyword](https://docs.mentio.dev/api/keywords/update-keyword.mdx): Mute or unmute it, reclassify it (`kind`), change the platforms it is tracked on, its classifier `context`, or its `matching` rules (each rule field optional; an empty list clears one). Rules apply to new mentions from the next poll; stored mentions are untouched.
- [Invite a member](https://docs.mentio.dev/api/members/create-invitation.mdx): Send an email invitation to join the workspace as admin or member; it expires after 48 hours. Idempotent: an address that already holds an open invitation gets it back with 200 and no second email. An address that is already a member is a 409 already_member. Team changes need a signed-in owner or admin (an OAuth token from an MCP sign-in, or the dashboard session): an API key answers 403.
- [List pending invitations](https://docs.mentio.dev/api/members/list-invitations.mdx): Invitations sent and not yet accepted, declined or expired. An accepted one appears in GET /v1/members instead.
- [List members](https://docs.mentio.dev/api/members/list-members.mdx): Everyone in the workspace, owners first. `userId` is what a mention's assigneeId and a person's ownerId take.
- [Remove a member](https://docs.mentio.dev/api/members/remove-member.mdx): The person loses the workspace within a minute (their dashboard session on the next request, an OAuth token when its short cache lapses). Their mentions, notes and outreach stay. Needs a signed-in owner or admin; only an owner removes another owner, and the last owner cannot be removed (409 last_owner).
- [Revoke an invitation](https://docs.mentio.dev/api/members/revoke-invitation.mdx): The link in the email stops working at once. Needs a signed-in owner or admin; an API key answers 403.
- [Export mentions as CSV](https://docs.mentio.dev/api/mentions/export-mentions-csv.mdx): The same mentions GET /v1/mentions would list for these filters, as CSV, newest matched first (the order they entered your feed, which can differ from the post date): id, published_at, platform, keyword, author, author_url, author_followers, relevance, sentiment, intents (pipe-separated), status, relevant, delivered, url, text (first 1,000 characters). Capped at 10,000 rows; the X-Mentions-Truncated header says when the cap cut the list. At most 6 exports per minute per workspace; a 429 carries Retry-After.
- [Get a mention](https://docs.mentio.dev/api/mentions/get-mention.mdx): One mention by id, as it appears in the list: the post, its author with reach and your tags, the classification, the priority score and the triage fields. Ids belong to your organization; any other id is a 404.
- [List mentions](https://docs.mentio.dev/api/mentions/search-mentions.mdx): Mentions matched to your keywords, filtered and paginated. Default order is newest match first; sort=priority ranks the last 30 days of matches by attention score. Page with nextCursor, passing the same filters and sort. A mention is one post matched to one keyword. alertId applies an alert rule's filter on top of the others: the same mentions that rule would send.
- [Update a mention](https://docs.mentio.dev/api/mentions/update-mention.mdx): The one write on a mention. Set status to ignored or done to handle it (open puts it back), assign it to a workspace member, snooze it out of the feed, leave an internal note, or correct the classifier: `relevant` true or false is your verdict (relevance becomes 100 or 0, and every list, filter, digest and report follows it), `sentiment` replaces the label; null withdraws a verdict and restores the classifier's value. Omitted fields are untouched. Delivery and billing never change.
- [Delete an outreach activity](https://docs.mentio.dev/api/people/delete-person-activity.mdx): Remove a contact logged by mistake. The person's owner and stage stay as they are.
- [Export people as CSV](https://docs.mentio.dev/api/people/export-people-csv.mdx): The same list as GET /v1/people (segmentId included) as CSV, one row per person with their contact columns: handle, followers, email, website, company, location, tags, then outreach stage, owner and last contacted. Capped at 5,000 people. At most 6 exports per minute per workspace; a 429 carries Retry-After.
- [Get a person](https://docs.mentio.dev/api/people/get-person.mdx): One person as your workspace sees them. An account merged into someone resolves to that person.
- [List people](https://docs.mentio.dev/api/people/list-people.mdx): The people behind your mentions: one row per person, with their accounts, reach, public profile, per-workspace stats, your annotations and where your outreach stands. Filter by platform, tag, follower range, mention counts, intents seen, keyword kinds mentioned or never mentioned, outreach stage, owner, automated (bot accounts, whose matched posts are mostly machine-made), or a saved segment. Offset-paginated with a total.
- [List outreach activities](https://docs.mentio.dev/api/people/list-person-activities.mdx): Every logged contact with this person across all their accounts, newest first (at most 200): who reached out, the channel, when, and a short note. Read it before reaching out so two teammates never contact the same person without knowing.
- [Log an outreach activity](https://docs.mentio.dev/api/people/log-person-activity.mdx): Record that a teammate reached out to this person: an email, a DM, a call. The first activity claims an unowned person for whoever reached out and moves not_contacted to contacted; an existing owner and a later stage are kept. `memberId` defaults to the signed-in member; an API key that omits it logs an unattributed activity, which claims nobody.
- [Merge an account into a person](https://docs.mentio.dev/api/people/merge-people.mdx): Declare that this account and another person are the same human, for your workspace only. Their mentions, tags, notes and outreach activities combine under the person named by `into`, which keeps its owner and stage unless it had none.
- [Undo a merge](https://docs.mentio.dev/api/people/split-person.mdx): The account becomes its own person again.
- [Update your annotations on a person](https://docs.mentio.dev/api/people/update-person.mdx): Tags, notes, mute, and the outreach owner (a workspace member; null clears) and stage, for your workspace only. Mute hides their posts from your feed and every channel; ingest and billing never change.
- [Create a segment](https://docs.mentio.dev/api/segments/create-segment.mdx)
- [Delete a segment](https://docs.mentio.dev/api/segments/delete-segment.mdx): Nobody in it is affected.
- [Get a segment](https://docs.mentio.dev/api/segments/get-segment.mdx)
- [List segments](https://docs.mentio.dev/api/segments/list-segments.mdx): Your saved segments, each with the number of people in it right now (segments are evaluated on every read, never materialized), plus presets you can save as a starting point. Pass a segment id to GET /v1/people to list its members.
- [Update a segment](https://docs.mentio.dev/api/segments/update-segment.mdx)
- [Get Health](https://docs.mentio.dev/api/system/get-health.mdx)
- [Get usage and balance](https://docs.mentio.dev/api/usage/get-usage.mdx): The prepaid balance (ledger, pending mention charges, and the effective balance the stop rule reads), the daily burn and the days it buys, the keywords the wallet runs and pauses, the matches recorded today and over 30 days, and whether tracking is stopped or the balance is low. Every matched mention bills ($0.008), relevant or not; every active keyword bills $5 a month, charged daily.