---
title: "Quickstart"
description: "A keyword, the company profile, a search and a triage in five calls."
canonical: https://docs.mentio.dev/quickstart
markdown: https://docs.mentio.dev/quickstart.mdx
---

# Quickstart

A keyword, the company profile, a search and a triage in five calls.

Mentio watches developer platforms for the terms you care about (your product, your competitors, your space) and turns everything it finds into structured, classified mentions you can query, filter, and act on. Platforms include Bluesky, Hacker News, Reddit, X, GitHub, Stack Overflow, DEV, YouTube, LinkedIn, and news.

Everything is API-first: a REST API for your code, [SDKs](/sdks) for TypeScript and Python and a [CLI](/cli) generated from it, [webhooks](/webhooks) for what happens as it happens, and an [MCP server](/mcp) so AI agents can use your mention feed as a tool.

## Base URL and authentication

All endpoints live under `/v1` on your API host. Every request (except `/v1/health` and the OpenAPI spec) needs an API key in the `Authorization` header:

```bash
export MENTIONS_API_URL="https://your-api-host"
export MENTIONS_API_KEY="mk_live_..."
```

See [Authentication](/authentication) for key management.

## 1. Track a keyword

```bash
curl -X POST "$MENTIONS_API_URL/v1/keywords" \
  -H "Authorization: Bearer $MENTIONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "term": "your product name", "kind": "brand" }'
```

```json
{
  "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"
}
```

`kind` is `brand` (default), `competitor`, or `topic`. `platforms` restricts the keyword to some platforms; `null` means all of them. A common word takes `matching` rules (terms the post must also contain, terms and authors that drop it, case sensitivity) and a `context` sentence for the classifier; see [How it works](/how-it-works#matching-rules).

## 2. Set your company profile

The classifier scores every mention for relevance using what it knows about your company. This is the single biggest lever on result quality, so set it early:

```bash
curl -X PATCH "$MENTIONS_API_URL/v1/company" \
  -H "Authorization: Bearer $MENTIONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme", "description": "We build X for Y.", "useCases": ["Ship Z without W"] }'
```

The profile is composed into the `context` the classifier reads. Send `context` directly to override it.

## 3. Search your mentions

New mentions flow in as each platform is polled (see [How it works](/how-it-works) for per-platform freshness). Query them with filters:

```bash
curl -H "Authorization: Bearer $MENTIONS_API_KEY" \
  "$MENTIONS_API_URL/v1/mentions?minRelevance=50&sentiment=positive&limit=25"
```

```json
{
  "data": [
    {
      "id": "mm_7f3a...",
      "status": "open",
      "relevant": true,
      "delivered": true,
      "priority": 61.5,
      "keyword": { "id": "kw_60d9...", "term": "your product name" },
      "post": {
        "platform": "hackernews",
        "url": "https://news.ycombinator.com/item?id=...",
        "text": "We migrated our side project last month and the DX was surprisingly good...",
        "publishedAt": "2026-09-03T08:12:44.000Z",
        "replyTo": null
      },
      "author": {
        "id": "aut_1c2d...",
        "name": "pg_fan",
        "handle": null,
        "url": "https://news.ycombinator.com/user?id=pg_fan",
        "avatarUrl": null,
        "followers": null,
        "tags": []
      },
      "classification": {
        "relevance": 86,
        "sentiment": "positive",
        "intents": ["praise"],
        "automated": false,
        "language": "en",
        "note": "Positive firsthand report of building on the product.",
        "failed": false,
        "feedback": null
      },
      "triage": { "assignee": null, "snoozedUntil": null, "note": null },
      "createdAt": "2026-09-03T08:15:02.113Z"
    }
  ],
  "nextCursor": null
}
```

Results are newest first and keyset-paginated: pass `nextCursor` back as `cursor` until it comes back `null`. Every list and resource follows the same rules, see [Conventions](/conventions).

## 4. Triage

Close a mention out, or hide it; ignored and done mentions are excluded from delivery:

```bash
curl -X PATCH "$MENTIONS_API_URL/v1/mentions/mm_7f3a..." \
  -H "Authorization: Bearer $MENTIONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "done" }'
```

## 5. Hear about it

Get mentions pushed instead of polled: a [webhook](/webhooks) for your code, or [Slack](/alerts/slack), [Telegram](/alerts/telegram) and email through [Alerts](/alerts).

## Next steps

<Cards>
  <Card title="Authentication" description="API keys, scopes, and key management." href="/authentication" />

  <Card title="How it works" description="The pipeline, per-platform freshness, and mention lifecycle." href="/how-it-works" />

  <Card title="TypeScript SDK" description="One typed function per endpoint, generated from the spec." href="/sdks" />

  <Card title="CLI" description="Every endpoint as a mentio command, plus a live feed." href="/cli" />

  <Card title="MCP server" description="Give AI agents tools over your mention feed." href="/mcp" />

  <Card title="OpenClaw" description="A ClawHub skill: track, search, triage and alert from natural language." href="/integrations/openclaw" />

  <Card title="Webhooks" description="Signed JSON for every mention or digest, with retries." href="/webhooks" />

  <Card title="Alerts" description="Rules and channels: Slack, Telegram, email, webhooks." href="/alerts" />

  <Card title="API Reference" description="Every endpoint, generated from the OpenAPI spec." href="/api" />
</Cards>