Mentio

https://docs.mentio.dev/
Admin
Mentio is an API-first social listening platform that tracks keywords across developer and social...
Tokens:265,418
Snippets:1,586
Trust Score:2.8
Update:1 week ago
Show doc for...
Tokens:
Raw
### POST /v1/slack/install

Source: https://docs.mentio.dev/alerts/slack

Starts the Slack installation flow and returns a URL to send the user to for authorization.

```APIDOC
## POST /v1/slack/install

### Description
Starts the Slack installation flow and returns a URL to send the user to for authorization.

### Method
POST

### Endpoint
/v1/slack/install

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for API authentication.

### Request Example
```
curl -X POST "$MENTIONS_API_URL/v1/slack/install" \
  -H "Authorization: Bearer $MENTIONS_API_KEY"
```

### Response
#### Success Response (200)
- **url** (string) - The Slack OAuth authorization URL to redirect the user to.

#### Response Example
```
{ "url": "https://slack.com/oauth/v2/authorize?..." }
```

```

--------------------------------

### curl example for GET /v1/keywords with filters

Source: https://docs.mentio.dev/changelog

Example of calling the Mentio API to list keywords with filters for kind, status, and sort. Uses the MENTIO_API_KEY environment variable for authorization.

```bash
curl "https://api.mentio.dev/v1/keywords?kind=competitor&status=active&sort=mentions&limit=20" \
  -H "Authorization: Bearer $MENTIO_API_KEY"
```

--------------------------------

### Response from GET /v1/whoami

Source: https://docs.mentio.dev/authentication

Example JSON response from the whoami endpoint, showing the workspace, authentication kind, scope, and key details.

```json
{
  "workspace": { "id": "org_...", "name": "Acme" },
  "auth": { "kind": "api_key", "scope": "write", "apiKeyId": "key_...", "expiresAt": null },
  "user": null
}
```

--------------------------------

### 200 response body for GET /v1/usage

Source: https://docs.mentio.dev/api/usage/get-usage

Example success response with all fields. The balance is in cents, burn shows daily burn and days left, keywords lists active/paused/capped counts and limit, mentions shows today and last30d counts, and stopped/lowBalance are booleans.

```json
{
  "balance": {
    "cents": 0,
    "pendingCents": 0,
    "effectiveCents": 0,
    "currency": "USD"
  },
  "burn": {
    "perDayCents": 0,
    "daysLeft": 0
  },
  "keywords": {
    "active": 0,
    "paused": 0,
    "capped": 0,
    "limit": 0,
    "dayCents": 0
  },
  "mentions": {
    "today": 0,
    "last30d": 0
  },
  "stopped": true,
  "lowBalance": true,
  "lastTopUpAt": "string"
}
```

--------------------------------

### cURL example for getting a keyword

Source: https://docs.mentio.dev/api/keywords/get-keyword

Executes a GET request to retrieve a keyword by its ID. Requires an API key in the Authorization header; replace the empty Bearer token with a valid key.

```bash
curl -X GET "https://api.mentio.dev/v1/keywords/kw_abc123" \
  -H "Authorization: Bearer "
```

--------------------------------

### 200 response example for Get a keyword

Source: https://docs.mentio.dev/api/keywords/get-keyword

Example of the 200 response body returned by the Get a keyword endpoint when successful. Contains the full keyword configuration including matching rules, stats, polling status, and cost breakdown.

```json
{
  "id": "string",
  "term": "string",
  "kind": "brand",
  "muted": true,
  "pausedForBalance": true,
  "pausedForNoise": true,
  "pausedForCap": true,
  "cap": {
    "mentions": 1,
    "welcome": true,
    "own": 0
  },
  "comments": {
    "enabled": true,
    "maxPerPost": 1
  },
  "group": {
    "id": "string",
    "name": "string",
    "externalId": "string",
    "isDefault": true
  },
  "platforms": [
    "bluesky"
  ],
  "feeds": [
    {
      "url": "string",
      "title": "string",
      "connectedAt": "string"
    }
  ],
  "reviewSources": [
    {
      "platform": "appstore",
      "id": "string",
      "url": "string",
      "countries": [
        "string"
      ],
      "language": "string",
      "connectedAt": "string"
    }
  ],
  "context": "string",
  "matching": {
    "requiredTerms": [
      "string"
    ],
    "requiredMode": "any",
    "excludedTerms": [
      "string"
    ],
    "excludedAuthors": [
      "string"
    ],
    "caseSensitive": true,
    "exactPhrase": true,
    "subreddits": {
      "only": [
        "string"
      ],
      "excluded": [
        "string"
      ]
    },
    "repositories": {
      "events": [
        "new"
      ],
      "minStars": 1000000,
      "minWeeklyStars": 25
    }
  },
  "stats": {
    "mentions": 0,
    "relevant": 0,
    "last7d": 0,
    "thisMonth": 0,
    "lastMentionAt": "string",
    "feedback": {
      "relevant": 0,
      "notRelevant": 0
    },
    "noise": {
      "scored": 0,
      "relevant": 0,
      "noisy": true
    },
    "health": "healthy",
    "cost": {
      "keywordDays": 0,
      "keywordCents": 0,
      "billableMentions": 0,
      "mentionCents": 0,
      "billableComments": 0,
      "commentCents": 0,
      "totalCents": 0
    }
  },
  "polling": [
    {
      "platform": "bluesky",
      "lastPolledAt": "string",
      "emptyPolls": 0
    }
  ],
  "createdAt": "string"
}
```

--------------------------------

### cURL request to get usage breakdown

Source: https://docs.mentio.dev/api/usage/get-usage-breakdown

Sends a GET request to the usage breakdown endpoint with an Authorization header. The bearer token is empty in the example.

```bash
curl -X GET "https://api.mentio.dev/v1/usage/breakdown" \
  -H "Authorization: Bearer "
```

--------------------------------

### Install and show CLI help

Source: https://docs.mentio.dev/cli

Install the Mentio CLI globally and display its help. The CLI exposes every public endpoint as a noun:verb command generated from the OpenAPI document.

```bash
npm install -g @mentio-dev/cli
mentio --help
```

--------------------------------

### cURL request to get a segment

Source: https://docs.mentio.dev/api/segments/get-segment

Sends a GET request to retrieve a segment by its ID. Uses the Authorization header with a bearer token. The example requests segment seg_abc123.

```bash
curl -X GET "https://api.mentio.dev/v1/segments/seg_abc123" \
  -H "Authorization: Bearer "
```

--------------------------------

### POST /v1/keywords

Source: https://docs.mentio.dev/quickstart

Creates a new keyword to track. This is the first step in the quickstart flow and returns the created keyword object.

```APIDOC
## POST /v1/keywords

### Description
Creates a new keyword to track. Returns the created keyword object with its configuration, stats, and polling details.

### Method
POST

### Endpoint
/v1/keywords

### Parameters
#### Request Body
- **term** (string) - Required - The keyword term to track.
- **kind** (string) - Required - The kind of keyword: `brand` (default), `competitor`, or `topic`.
- **platforms** (array|null) - Optional - Restricts the keyword to specific platforms; `null` means all platforms.
- **matching** (object) - Optional - Matching rules: `requiredTerms` (array), `requiredMode` (string: "any"), `excludedTerms` (array), `excludedAuthors` (array), `caseSensitive` (boolean).
- **context** (string|null) - Optional - A context sentence for the classifier.

### Request Example
{
  "term": "your product name",
  "kind": "brand"
}

### Response
#### Success Response (200)
- **id** (string) - The keyword ID.
- **term** (string) - The keyword term.
- **kind** (string) - The keyword kind.
- **muted** (boolean) - Whether the keyword is muted.
- **platforms** (array|null) - Platforms the keyword is restricted to.
- **context** (string|null) - Context sentence for classifier.
- **matching** (object) - Matching rules object.
- **stats** (object) - Statistics object with mention counts.
- **polling** (array) - Polling configuration.
- **createdAt** (string) - Creation timestamp.

#### Response Example
{
  "id": "kw_60d99e99b03549fb8eb81df038d10f86",
  "term": "your product name",
  "kind": "brand",
  "muted": false,
  "platforms": null,
  "context": null,
  "matching": { "requiredTerms": [], "requiredMode": "any", "excludedTerms": [], "excludedAuthors": [], "caseSensitive": false },
  "stats": { "mentions": 0, "relevant": 0, "last7d": 0, "lastMentionAt": null, "feedback": { "relevant": 0, "notRelevant": 0 } },
  "polling": [],
  "createdAt": "2026-09-03T10:04:44.881Z"
}
```

--------------------------------

### CLI command example

Source: https://docs.mentio.dev/sdks

Example of using the Mentio CLI to search mentions with JSON output, piped to a script. Any language that can run a process can use this.

```bash
mentio mentions:search --relevant true | your-script
```

--------------------------------

### Example commands by area

Source: https://docs.mentio.dev/cli

Example commands for each command area: Keywords, Mentions, People and segments, Analytics, Alerts and channels. Ids are positional; flags are named exactly as in the API. Every flag takes a value, booleans included (--muted false). Lists are comma-separated, nested objects are JSON, and null clears a nullable field.

```bash
mentio keywords:list
mentio keywords:create --term "acme" --kind brand --platforms reddit,hackernews
mentio keywords:update kw_60d9... --muted true
mentio mentions:search --relevant true --sentiment negative --limit 50
mentio mentions:update mm_7f3a... --status done --note "Replied in thread"
mentio people:list --minFollowers 5000 --sort reach
mentio analytics:summary --range 7d --compare true --timezone Europe/Madrid
mentio analytics:breakdown --by platform --range 30d
mentio channels:create --kind webhook --url https://example.com/hooks/mentio
mentio alerts:create --name "Buying signals" --event mention.buy_intent --filter '{"intents":["buy_intent"]}' --channelIds dest_...
```

--------------------------------

### POST /v1/top-up-checkout

Source: https://docs.mentio.dev/api/auth/whoami

Creates a hosted checkout URL with `amountCents` prefilled (editable there, $20 to $5,000). The balance is credited when the payment lands, within a minute, and tracking the wallet had paused resumes at once. Nothing is charged by this call itself. `successUrl` must be on an origin this deployment trusts; omit it for the dashboard's billing page.

```APIDOC
## POST /v1/top-up-checkout

### Description
Creates a hosted checkout URL with `amountCents` prefilled (editable there, $20 to $5,000). The balance is credited when the payment lands, within a minute, and tracking the wallet had paused resumes at once. Nothing is charged by this call itself. `successUrl` must be on an origin this deployment trusts; omit it for the dashboard's billing page.

### Method
POST

### Endpoint
/v1/top-up-checkout
```

--------------------------------

### GET /v1/segments

Source: https://docs.mentio.dev/llms.txt

Lists 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.

```APIDOC
## GET /v1/segments

### Description
List segments. Returns your saved segments with current member counts and presets.

### Method
GET

### Endpoint
/v1/segments

### Response
#### Success Response (200)
An array of segment objects.

#### Response Example
[
  {
    "id": "string",
    "name": "string",
    "count": 0
  }
]

```

--------------------------------

### Check API key and restart gateway

Source: https://docs.mentio.dev/integrations/openclaw

Use these commands to verify the MENTIO_API_KEY in ~/.openclaw/.env and restart the gateway, which reads the .env file only on start. Run them when a 401 error occurs.

```bash
grep MENTIO_API_KEY ~/.openclaw/.env
openclaw gateway restart
```

--------------------------------

### Authenticate with API key (flag, env, or auth:set)

Source: https://docs.mentio.dev/cli

Three alternative ways to authenticate, in order of precedence: a flag for one call, an environment variable for CI, or a stored key. For a self-hosted deployment add --api-url, MENTIO_API_URL, or auth:set --url.

```bash
mentio keywords:list --api-key mk_live_...      # a flag, for one call
export MENTIO_API_KEY=mk_live_...               # the environment, for CI
mentio auth:set --key mk_live_...               # a key you already have
```

--------------------------------

### Get mention response body

Source: https://docs.mentio.dev/api/mentions/get-mention

Example JSON response body for the get-mention endpoint. Shows the mention fields returned by the API.

```json
{
  "id": "string",
  "status": "open",
  "relevant": true,
  "delivered": true,
  "priority": 0,
  "keyword": {
    "id": "string",
    "term": "string",
    "group": {
      "id": "string",
      "name": "string",
      "externalId": "string",
      "isDefault": true
    }
  }
}
```

--------------------------------

### 200 response body for GET /v1/health

Source: https://docs.mentio.dev/api/system/get-health

Example success response returned by the health endpoint. Contains a single field 'ok' set to true.

```json
{
  "ok": true
}
```

--------------------------------

### Install @mentio-dev/sdk with npm

Source: https://docs.mentio.dev/sdks/typescript

Install the @mentio-dev/sdk package using npm. Requires Node 22+ or compatible runtimes (Bun, Deno, browsers); no runtime dependencies.

```bash
npm install @mentio-dev/sdk
```

--------------------------------

### cURL request to search mentions

Source: https://docs.mentio.dev/api/mentions/search-mentions

Sends a GET request to the /v1/mentions endpoint with an Authorization header. The bearer token is left empty in the example.

```bash
curl -X GET "https://api.mentio.dev/v1/mentions" \
  -H "Authorization: Bearer "
```

--------------------------------

### Install the mentio skill from ClawHub

Source: https://docs.mentio.dev/integrations/openclaw

Run this command in your OpenClaw environment to install the Mentio skill. It requires an API key set in the MENTIO_API_KEY environment variable and a running OpenClaw installation.

```bash
npx clawhub@latest --workdir ~/.openclaw install mentio
```

--------------------------------

### Mention Event Payload

Source: https://docs.mentio.dev/webhooks/mention-events

An example of the webhook payload sent for each mention that matches an instant rule. The `data` object mirrors the response of `GET /v1/mentions/{id}`.

```APIDOC
## Webhook Event: Mention

### Description
An `instant` rule sends one request per mention that passes its filter, right after the classifier scored it. The `data` field is the mention exactly as `GET /v1/mentions/{id}` returns it.

### Event Payload
```json
{
  "id": "dlv_9c1e...",
  "event": "mention.buy_intent",
  "createdAt": "2026-09-03T08:15:04.201Z",
  "alert": { "id": "feed_2b7d...", "name": "Buying signals" },
  "data": {
    "id": "mm_7f3a...",
    "status": "open",
    "relevant": true,
    "delivered": false,
    "priority": 74.2,
    "keyword": {
      "id": "kw_60d9...",
      "term": "your product name",
      "group": { "id": "grp_7f3a...", "name": "Default", "externalId": null, "isDefault": true },
      "matchedAs": "phrase",
      "matchedIn": "text"
    },
    "post": {
      "platform": "reddit",
      "kind": "post",
      "url": "https://www.reddit.com/r/devops/comments/...",
      "title": "Switching monitoring tools, worth it?",
      "text": "Switching monitoring tools, worth it?\n\nWe're evaluating your product name vs the incumbent for our team, anyone switched recently?",
      "imageUrl": null,
      "subreddit": "devops",
      "flair": "Discussion",
      "repository": null,
      "links": [],
      "engagement": { "likes": 42, "reposts": null, "replies": 17, "quotes": null, "views": null, "bookmarks": null },
      "publishedAt": "2026-09-03T08:12:44.000Z",
      "replyTo": null
    },
    "author": {
      "id": "aut_1c2d...",
      "name": "ops_lead",
      "handle": "u/ops_lead",
      "url": "https://www.reddit.com/user/ops_lead",
      "avatarUrl": null,
      "followers": 1240,
      "tags": ["prospect"]
    },
    "classification": {
      "relevance": 91,
      "sentiment": "neutral",
      "intents": ["buy_intent", "question"],
      "automated": false,
      "language": "en",
      "confidence": 0.82,
      "uncertain": false,
      "note": "Team lead comparing the product against an incumbent before switching.",
      "failed": false,
      "feedback": null
    },
    "review": null,
    "triage": { "assignee": null, "snoozedUntil": null, "note": null },
    "duplicateOf": null,
    "duplicates": [],
    "createdAt": "2026-09-03T08:15:02.113Z"
  }
}
```

### Field Descriptions
- **id** (string) - The delivery ID of the webhook event.
- **event** (string) - The event type, e.g., `mention.buy_intent`.
- **createdAt** (string) - Timestamp of when the event was created.
- **alert** (object) - The alert/rule that triggered the event, containing `id` and `name`.
- **data** (object) - The mention object, identical to the response from `GET /v1/mentions/{id}`.

### Behavior Notes
- **Relevant mentions by default**: A rule without `minRelevance` sends mentions scored 40 and up, so `data.relevant` is `true`. With `minRelevance` under 40, it also receives noise matches with `data.relevant` `false` and the score in `data.classification.relevance`. Email channels keep the 40 line regardless.
- **`data.delivered`** describes the moment the payload was built, before this request was sent, so it is usually `false` in the payload itself.
- **`data.id`** is the mention id (`mm_...`). Use it to `PATCH /v1/mentions/{id}` from your own tooling: set `status` to `done` once handled, or `assigneeId` to route it.
- **One post, several keywords, several events**: A post matching two keywords arrives once per keyword, each with its own `data.id` and `data.keyword`.
- **A cross-post arrives once**: When the same author posts the same text again for the same keyword within three days, only the first sends an event; the copies are listed later as `duplicates` when reading the mention. In the event itself `duplicates` is empty.
- **Comments and repositories are mentions too**: `data.post.kind` is `post`, `comment`, or `repository`.

### Branching on the Payload
| Route on | Field |
|---|---|
| The rule | `event`, `alert.id` |
| The keyword | `data.keyword.term`, `data.keyword.id` |
| The platform | `data.post.platform` |
| Sentiment, intents, score | `data.classification.sentiment`, `data.classification.intents`, `data.classification.relevance` |
| Who wrote it | `data.author.followers`, `data.author.tags` |
| Attention | `data.priority` |
```

--------------------------------

### Configure MCP server (mcp:config)

Source: https://docs.mentio.dev/cli

Print MCP server configuration with your key filled in. Default prints the claude mcp add command; --client cursor and --client vscode print JSON for their respective config files.

```bash
mentio mcp:config                    # the `claude mcp add` command
mentio mcp:config --client cursor    # JSON for .cursor/mcp.json
mentio mcp:config --client vscode    # JSON for .vscode/mcp.json
```

--------------------------------

### cURL request to export mentions

Source: https://docs.mentio.dev/api/mentions/export-mentions-json

Sends a GET request to the export endpoint with a Bearer token authorization header. The token value is left empty in the example.

```bash
curl -X GET "https://api.mentio.dev/v1/mentions/export.json" \
  -H "Authorization: Bearer "
```

--------------------------------

### Get a group with cURL

Source: https://docs.mentio.dev/api/groups/get-group

Fetches a group by its id (grp_...) using the bearer token from POST /v1/api-keys. The Authorization header value is left empty in the example.

```bash
curl -X GET "https://api.mentio.dev/v1/groups/grp_abc123" \
  -H "Authorization: Bearer "
```

--------------------------------

### Install mentio

Source: https://docs.mentio.dev/sdks/python

Install the mentio package from PyPI. Requires Python 3.11 or newer.

```bash
pip install mentio
```

--------------------------------

### 200 response body for GET /v1/analytics/summary

Source: https://docs.mentio.dev/api/analytics/get-analytics-summary

Example success response with window details, matched/relevant counts, sentiment, buy intent, questions, reach, triage metrics, and optional previous period.

```json
{
  "window": {
    "from": "string",
    "to": "string",
    "days": 0,
    "timezone": "string"
  },
  "matched": 0,
  "relevant": 0,
  "posts": 0,
  "people": 0,
  "sentiment": {
    "positive": 0,
    "neutral": 0,
    "negative": 0,
    "unclassified": 0
  },
  "buyIntent": 0,
  "questions": 0,
  "reach": {
    "followers": 0,
    "people": 0
  },
  "triage": {
    "open": 0,
    "ignored": 0,
    "done": 0,
    "waiting": 0,
    "handledRate": 0,
    "medianTimeToDoneMs": 0
  },
  "previous": {
    "matched": 0,
    "relevant": 0,
    "posts": 0,
    "people": 0,
    "sentiment": {
      "positive": 0,
      "neutral": 0,
      "negative": 0,
      "unclassified": 0
    },
    "buyIntent": 0,
    "questions": 0,
    "reach": {
      "followers": 0,
      "people": 0
    },
    "triage": {
      "open": 0,
      "ignored": 0,
      "done": 0,
      "waiting": 0,
      "handledRate": 0,
      "medianTimeToDoneMs": 0
    }
  }
}
```

--------------------------------

### 200 response body for GET /v1/analytics/reviews

Source: https://docs.mentio.dev/api/analytics/get-reviews-report

Example 200 response body for the reviews analytics endpoint. Contains window details, totals, tags, per-page breakdowns, and optional previous period data.

```json
{
  "window": {
    "from": "string",
    "to": "string",
    "days": 0,
    "timezone": "string",
    "bucket": "day"
  },
  "totals": {
    "reviews": 0,
    "averageRating": 1,
    "distribution": {
      "1": 0,
      "2": 0,
      "3": 0,
      "4": 0,
      "5": 0
    },
    "responded": 0,
    "openNegative": 0
  },
  "tags": [
    {
      "tag": "string",
      "count": 0
    }
  ],
  "pages": [
    {
      "reviews": 0,
      "averageRating": 1,
      "distribution": {
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 0
      },
      "responded": 0,
      "openNegative": 0,
      "platform": "appstore",
      "id": "string",
      "url": "string",
      "series": [
        {
          "date": "string",
          "reviews": 0,
          "averageRating": 1
        }
      ],
      "previous": {
        "reviews": 0,
        "averageRating": 1
      }
    }
  ],
  "previous": {
    "reviews": 0,
    "averageRating": 1,
    "distribution": {
      "1": 0,
      "2": 0,
      "3": 0,
      "4": 0,
      "5": 0
    },
    "responded": 0,
    "openNegative": 0
  }
}
```

--------------------------------

### createMentio

Source: https://docs.mentio.dev/sdks/typescript

Creates a Mentio client instance with the provided configuration, binding the API key and host.

```APIDOC
## createMentio

### Description
Creates a Mentio client instance that binds the API key and host. All subsequent API calls are made through this client.

### Method
Function

### Signature
```typescript
createMentio(config: { apiKey: string; baseUrl?: string; fetch?: typeof fetch; headers?: Record<string, string> }): MentioClient
```

### Parameters
- **apiKey** (string) - Required - The API key for authentication.
- **baseUrl** (string) - Optional - The base URL for the API. Defaults to the standard Mentio API URL.
- **fetch** (function) - Optional - A custom fetch implementation.
- **headers** (object) - Optional - Additional headers to include with every request.

### Example
```typescript
const mentio = createMentio({ apiKey: process.env.MENTIO_API_KEY! });
```

### Response
Returns a `MentioClient` instance with methods for each endpoint.
```
Tokens:
Raw