Developers
Bring Refinea data into your own tools: the public API for dashboards and data warehouses, the MCP server for AI assistants.
In this chapter
Bring Refinea data into your own tools: the public API for dashboards and data warehouses, the MCP server for AI assistants.
Public API
Use the Refinea API to pull your visibility data into your own dashboards, your data warehouse, or a Slack bot. Twelve read endpoints, one header.
| Endpoint | What it returns |
|---|---|
| Domains | The sites tracked by your account. |
| Overview | A single-call summary for a domain, with the previous period for deltas. |
| Mentions aggregate | Visibility, share of voice and competitor rankings, per model and per day. |
| Mentions | Every brand mention extracted from AI answers (paginated). |
| Sentiment timeseries | Daily polarity rollup, plus the window's score. |
| Topics | The same metrics broken down by the subjects you track. |
| Personas | The buyer profiles the questions are asked from. |
| Prompts | The questions being monitored, with their topic and persona. |
| Prompts metrics | Per-prompt metrics, latest run or aggregated over the window. |
| Citations | Which sites and pages the models cite, ranked by share. |
| Sources | The pages each model cited, grouped by prompt. |
| Search queries | The searches each AI ran before answering. |
Two numbers people confuse
| Field | Meaning |
|---|---|
visibility_rate |
How often you appear at all: answers naming you, over answers analysed. |
share_of_voice |
How much of the conversation is yours: your appearances over yours plus every competitor's. |
They answer different questions and routinely differ by an order of magnitude. Competitors you archived are excluded from both the lists and the denominators, exactly as in the app.
Changed September 2026: the field
sovwas removed. It carried two different formulas under one name and neither was the share of voice. Usevisibility_rateorshare_of_voice.
Authenticate
Every request needs an X-API-Key header. API access is part of the Pro plan: to get a key, ask your Refinea contact or write to [email protected]. A key reads only, or reads and writes through the MCP server.
curl https://api.refinea.io/public/domains \
-H "X-API-Key: $REFINEA_KEY"
A key is shown once, when you create it. Store it somewhere safe: if you lose one, revoke it and create a new one.
Reference
| Format | Where |
|---|---|
| Swagger UI | Interactive reference at api.refinea.io/public/swagger |
| ReDoc | The same reference, ReDoc layout, at api.refinea.io/public/redoc |
| OpenAPI schema | Machine-readable spec at api.refinea.io/public/openapi.json |
The introduction on the ReDoc page is the full narrative guide: what each number means and how the windows work. The endpoint reference below it is generated from the code.
MCP server
The same data, exposed as tools an AI assistant can call while it talks to you. Ask "how did we do this month" in Claude or ChatGPT and the assistant calls Refinea, gets the numbers, and writes the answer. Nothing is copied or cached: it reads what the dashboard reads, at the moment you ask.
Connect
| Setting | Value |
|---|---|
| Address | https://api.refinea.io/mcp |
| Transport | Streamable HTTP |
| Authentication | OAuth, or your API key as a bearer token |
In Claude, ChatGPT and most chat assistants, add the address as a custom connector and sign in to Refinea when asked: that is the OAuth route, and it needs no key. The clients you connect this way are listed in Settings, under AI assistants, with the date they last read and a Revoke button. With a key, from a terminal:
claude mcp add --transport http refinea https://api.refinea.io/mcp \
--header "Authorization: Bearer $REFINEA_KEY"
The header differs from the REST API. There it is
X-API-Key, here it isAuthorization: Bearer, because the MCP transport specifies bearer authentication. Same key either way.
What it gives the assistant
Fifty-five tools and five briefs. Every tool takes a domain name, a brand name or an id, and the metric tools take the dashboard's filters: model, topic, persona, persona or generic prompts, a date range.
| Group | What the assistant can read or do |
|---|---|
| Numbers | Visibility, competitors, citations, sentiment, topics, per-prompt performance, two periods compared, trends day by day or week by week. |
| Answers | What a model actually answered to a prompt, the searches it ran, two brands compared prompt by prompt and the sources behind the gap. |
| Your setup | Prompts, topics, personas, brand identity, Brand Kit, monitored pages, skills, the AI crawlers reading your site. |
| Work | The Actions Refinea raised, the workflows with their runs, schedules and sheets, publishing to your CMS. |
| Agents | Building a new agent from a description through Refinea's planner, and changing one you have, checked by the editor's own validator. |
The five briefs are a monthly report, a competitive briefing, content opportunities, what changed, and a diagnosis of the questions you lose. Each names the tools to call in order and fixes the shape of the answer.
Read-only by default
Every read tool says it only reads, so a client that asks before write actions will not ask before these. A connection allowed to write changes things in two steps: a proposal you read, then your yes. The propose tools are shown only to connections allowed to write.
Which assistants
Any client that speaks MCP. The rules for the chat products are the vendors': Claude takes either a key in a header or OAuth; ChatGPT takes remote servers in developer mode on paid plans, and only over OAuth; Gemini takes custom servers over streamable HTTP in its Enterprise edition. In a chatbot you build, your own code calls the tools and hands the results to whichever model you use.
A key reaches every domain on its account and nothing else. There is no per-domain key today, so if one assistant serves several brands, name the domain in every request.