DocsAPI & MCP

API and MCP overview

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

There are two ways to pull your data by code. Both run the same computations as the dashboard:

The v1 REST API: a read-only JSON API for your workspace's metrics. It has one write endpoint that takes crawler logs.
The MCP server: a Model Context Protocol endpoint. It offers the same reads as tools an AI agent can call.

Both read the same functions that draw your screens, so a field in the API and a number on the dashboard can never drift apart.

Base URL

Everything lives on 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

You create and scope keys on the API keys screen in settings. Authentication covers the three kinds of key and the scopes.

What's covered

REST and MCP expose the same fourteen read surfaces, each scoped to one brand.

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`
Fact check	`GET /api/v1/fact-check`	`get_fact_check`
Ads	`GET /api/v1/ads`	`list_ads`
Sentiment, with quotes	`GET /api/v1/sentiment`	`get_sentiment`
Metrics history	`GET /api/v1/metrics/history`	`get_metrics_history`
Crawler analytics	`GET /api/v1/crawlers`	`get_crawler_analytics`

Thirteen of the fourteen are on every tier. Crawler analytics needs Growth or above, the same gate as the /crawlers dashboard. One more endpoint takes AI-crawler logs: POST /api/v1/crawler-events.

The MCP server carries two extra tools with no REST twin. list_tag_groups serves the tag_groups block from the prompts envelope alone. run_fact_check is the one tool that is not a read. It triggers the same metered on-demand fact check as the dashboard. Field tables are in the Resource reference and on the MCP server page.

A first request

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

With more than one brand, add ?brand=<brandId>. Get the ids from /api/v1/brands. Leave it off and the request uses your first brand.

Conventions and guarantees

Read these before you build:

Conventions: which fields are 0–1 fractions, which are 0–100 scores, and which are counts. Also 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 on purpose:

Released fields never change meaning. Once a field ships, its name and meaning are frozen. New things arrive as additive fields beside the old one. Topic folders shipped as topic_id and topic_name next to the frozen topic. Code that keys 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 marked on charts. A field's numbers never change silently.
No existence leaks. A brand id outside your scope returns the same "unknown brand" response as an id that does not exist.

Build against these and your integration will not break under you.