DocsAPI & MCP

API and MCP overview

MentionFlow exposes a read-only v1 REST API and an MCP server over the same data your dashboard shows. Here is what they cover and the guarantees they make.

MentionFlow has two programmatic surfaces, both backed by the exact same computations as the dashboard:

The v1 REST API — a read-only JSON API for your workspace's metrics, plus one write endpoint for ingesting crawler logs.
The MCP server — a Model Context Protocol endpoint that exposes the same reads as tools an AI agent can call.

Because both are served from the same functions that render your screens, an API field and the number on the dashboard can never drift apart.

Base URL

Everything is served from your workspace host under /api:

https://mentionflow.ai/api/v1        REST
https://mentionflow.ai/api/mcp       MCP (Streamable HTTP)

There is no separate API subdomain — use the same host you sign in on.

Authentication in one line

Every request carries a workspace API key as a bearer token:

Authorization: Bearer mf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create and scope keys under Settings → API keys. Full details, including the three key kinds and scopes, are in Authentication.

What's covered

The REST API and MCP expose the same eleven read surfaces, brand-scoped:

Resource	REST	MCP tool
Brand list	`GET /api/v1/brands`	`list_brands`
Visibility scorecard	`GET /api/v1/overview`	`get_overview`
Prompts	`GET /api/v1/prompts`	`list_prompts`
Competitors	`GET /api/v1/competitors`	`list_competitors`
Sources	`GET /api/v1/sources`	`list_sources`
Cited URLs	`GET /api/v1/urls`	`list_urls`
Answers (receipts)	`GET /api/v1/answers`	`list_answers`
Shopping leaderboard	`GET /api/v1/shopping`	`list_shopping_products`
Shopping trend	`GET /api/v1/shopping-trend`	`get_shopping_trend`
Metrics history	`GET /api/v1/metrics/history`	`get_metrics_history`
Crawler analytics	`GET /api/v1/crawlers`	`get_crawler_analytics`

Plus one ingest endpoint, POST /api/v1/crawler-events, for streaming AI-crawler logs. Full field tables are in the Resource reference and MCP server pages.

A first request

curl https://mentionflow.ai/api/v1/overview \
  -H "Authorization: Bearer mf_your_key_here"

If you have more than one brand, add ?brand=<brandId> (get ids from /api/v1/brands); otherwise the request defaults to your first brand.

Conventions and guarantees

Read these before you build:

Conventions — the scale rules (which fields are 0–1 fractions vs 0–100 scores vs counts), the note fields, null handling, the fixed 7-day window, and which engines are blended.
Limits — the per-key rate limit (120 req/min, X-RateLimit-* headers), response caps, the MCP batch cap, and the ingest body cap.
Errors — the JSON error shapes and status codes.

Contract-freeze policy

The v1 surface is stable by design:

Released fields never change meaning. Once a field ships in a v1 response, its name and semantics are frozen. New capabilities arrive as additive fields alongside the old one — for example, topic folders shipped as new topic_id / topic_name fields next to the frozen topic, so a consumer keying on topic never sees it relabel.
Metric math is versioned separately. Any change to how a metric is computed bumps an internal METRICS_VERSION and is annotated on charts, rather than silently altering a field's numbers.
No existence leaks. A brand id outside your scope returns exactly the same "unknown brand" response as an id that doesn't exist.

Build against these and your integration won't break under you.