Documentation

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.

Tabella
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

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 sov was removed. It carried two different formulas under one name and neither was the share of voice. Use visibility_rate or share_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

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

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 is Authorization: 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.

What it gives the assistant
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.