Documentazione

Sviluppatori

Porta i dati di Refinea nei tuoi strumenti: l'API pubblica per dashboard e data warehouse, il server MCP per gli assistenti AI.

In questo capitolo

Porta i dati di Refinea nei tuoi strumenti: l'API pubblica per dashboard e data warehouse, il server MCP per gli assistenti AI.

API pubblica

Usa l'API di Refinea per portare i dati di visibilità nelle tue dashboard, nel tuo data warehouse o in un bot Slack. 12 endpoint di lettura, un solo header.

Tabella
Endpoint Cosa restituisce
Domains I siti monitorati dal tuo account.
Overview Un riepilogo di un dominio in una chiamata, con il periodo precedente per le variazioni.
Mentions aggregate Visibilità, share of voice e classifiche dei concorrenti, per modello e per giorno.
Mentions Ogni menzione di brand estratta dalle risposte AI (paginata).
Sentiment timeseries Il sentiment giorno per giorno, più il punteggio della finestra.
Topics Le stesse metriche divise per i temi che monitori.
Personas I profili di acquirente dai quali partono le domande.
Prompts Le domande monitorate, con tema e persona.
Prompts metrics Le metriche per prompt, dell'ultima esecuzione o aggregate sulla finestra.
Citations Quali siti e pagine citano i modelli, in ordine di quota.
Sources Le pagine citate da ogni modello, raggruppate per prompt.
Search queries Le ricerche fatte da ogni AI prima di rispondere.

Due numeri che si confondono

Due numeri che si confondono
Campo Significato
visibility_rate Quanto spesso compari: risposte che ti nominano, sulle risposte analizzate.
share_of_voice Quanta parte della conversazione è tua: le tue menzioni sulle tue più quelle di ogni concorrente.

Rispondono a domande diverse e spesso differiscono di un ordine di grandezza. I concorrenti archiviati sono esclusi sia dagli elenchi sia dai denominatori, esattamente come nell'app.

Cambiato a settembre 2026: il campo sov è stato tolto. Portava due formule diverse sotto lo stesso nome e nessuna era la share of voice. Usa visibility_rate o share_of_voice.

Autenticazione

Ogni richiesta ha bisogno dell'header X-API-Key. L'accesso all'API fa parte del piano Pro: per avere una chiave chiedi al tuo referente Refinea o scrivi a [email protected]. Una chiave può solo leggere, oppure leggere e scrivere attraverso il server MCP.

curl https://api.refinea.io/public/domains \
  -H "X-API-Key: $REFINEA_KEY"

Una chiave si vede una volta sola, quando viene creata. Conservala in un posto sicuro: se la perdi, revocala e creane una nuova.

Riferimento

Riferimento
Formato Dove
Swagger UI Riferimento interattivo su api.refinea.io/public/swagger
ReDoc Lo stesso riferimento, impaginato con ReDoc, su api.refinea.io/public/redoc
Schema OpenAPI La specifica leggibile dalle macchine su api.refinea.io/public/openapi.json

L'introduzione della pagina ReDoc è la guida completa: cosa vuol dire ogni numero e come funzionano le finestre. Il riferimento degli endpoint sotto è generato dal codice.

Server MCP

Gli stessi dati, come strumenti che un assistente AI può chiamare mentre parla con te. Chiedi "come siamo andati questo mese" in Claude o ChatGPT e l'assistente chiama Refinea, prende i numeri e scrive la risposta. Niente viene copiato o messo in cache: legge quello che legge la dashboard, nel momento in cui chiedi.

Collegarsi

Collegarsi
Impostazione Valore
Indirizzo https://api.refinea.io/mcp
Trasporto Streamable HTTP
Autenticazione OAuth, oppure la tua chiave API come bearer token

In Claude, ChatGPT e nella maggior parte degli assistenti in chat, aggiungi l'indirizzo come connettore personalizzato e accedi a Refinea quando te lo chiede: è la strada OAuth, e non serve una chiave. I client collegati così sono elencati in Impostazioni, sotto Assistenti AI, con la data dell'ultima lettura e il bottone per revocarli. Con una chiave, da terminale:

claude mcp add --transport http refinea https://api.refinea.io/mcp \
  --header "Authorization: Bearer $REFINEA_KEY"

L'header è diverso da quello dell'API REST. Lì è X-API-Key, qui è Authorization: Bearer, perché il trasporto MCP prevede l'autenticazione bearer. La chiave è la stessa.

Cosa dà all'assistente

55 strumenti e 5 brief. Ogni strumento accetta il nome di un dominio, il nome di un brand o un id, e gli strumenti di metrica accettano i filtri della dashboard: modello, tema, persona, prompt delle personas o generici, un intervallo di date.

Cosa dà all'assistente
Gruppo Cosa può leggere o fare l'assistente
Numeri Visibilità, concorrenti, citazioni, sentiment, temi, rendimento per prompt, due periodi a confronto, andamenti giorno per giorno o settimana per settimana.
Risposte Cosa ha risposto davvero un modello a un prompt, le ricerche che ha fatto, due brand confrontati prompt per prompt e le fonti dietro la differenza.
La tua configurazione Prompt, temi, personas, identità del brand, Brand Kit, pagine monitorate, skill, i crawler AI che leggono il tuo sito.
Lavoro Le Actions aperte da Refinea, i workflow con le loro esecuzioni, programmazioni e fogli, la pubblicazione sul tuo CMS.
Agenti Costruire un agente nuovo da una descrizione con il pianificatore di Refinea, e cambiarne uno esistente, controllato dallo stesso validatore dell'editor.

I cinque brief sono un report mensile, un confronto competitivo, le opportunità di contenuto, cosa è cambiato e una diagnosi delle domande su cui perdi. Ognuno indica gli strumenti da chiamare in ordine e fissa la forma della risposta.

Sola lettura di default

Ogni strumento di lettura dichiara che legge e basta, così un client che chiede conferma prima delle scritture non la chiede per questi. Una connessione autorizzata a scrivere cambia le cose in due passi: una proposta che leggi, poi il tuo sì. Gli strumenti di proposta si vedono solo nelle connessioni autorizzate a scrivere.

Quali assistenti

Qualsiasi client che parla MCP. Per i prodotti di chat le regole sono quelle dei fornitori: Claude accetta una chiave in un header oppure OAuth; ChatGPT accetta server remoti in modalità sviluppatore sui piani a pagamento, e solo con OAuth; Gemini accetta server personalizzati in streamable HTTP nella versione Enterprise. In un chatbot costruito da te, è il tuo codice a chiamare gli strumenti e a passare i risultati al modello che usi.

Una chiave raggiunge tutti i domini del suo account e nient'altro. Oggi non esiste una chiave per singolo dominio, quindi se un assistente serve più brand, indica il dominio in ogni richiesta.