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.
| 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
| 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. Usavisibility_rateoshare_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
| 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
| 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.
| 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.