API REST SEO per sviluppatori
Lo stesso motore di audit a 91 regole, accessibile via HTTP puro. Porta il tuo linguaggio: curl, Node, Python, PHP, qualsiasi cosa parli HTTPS. Le stesse chiavi API funzionano anche con il nostro server MCP.
Senza carta. Risultati in 30 secondi.
Oppure incolla un URL: lo stesso audit, senza installare nulla.
Aggiornato
Autenticazione con token Bearer
Ogni endpoint autenticato accetta un token nell'header Authorization: Authorization: Bearer ms_live_xxx. Genera una chiave su app.metricspot.com/settings/api-keys (fino a 10 per account). L'endpoint di audit anonimo funziona senza chiave, limitato a 1 audit per IP ogni 24 ore. Le stesse chiavi ms_live_ funzionano sia per questa API REST sia per il server MCP di MetricSpot.
curl
Endpoint anonimo, senza token. Restituisce la busta di audit completa inline.
curl -X POST https://app.metricspot.com/api/public/audit \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'Node (fetch)
Funziona in Node 18+, Bun, Deno e nei browser moderni. Senza dipendenze.
const res = await fetch("https://app.metricspot.com/api/audits", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer ms_live_xxx",
},
body: JSON.stringify({ url: "https://example.com" }),
});
const audit = await res.json();Python (httpx)
requests funziona allo stesso modo: sostituisci httpx.post con requests.post.
import httpx
res = httpx.post(
"https://app.metricspot.com/api/audits",
headers={"Authorization": "Bearer ms_live_xxx"},
json={"url": "https://example.com"},
)
audit = res.json()PHP
Estensione cURL standard, disponibile in ogni installazione di PHP dalla 4.0.
<?php
$ch = curl_init("https://app.metricspot.com/api/audits");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Authorization: Bearer ms_live_xxx",
],
CURLOPT_POSTFIELDS => json_encode(["url" => "https://example.com"]),
CURLOPT_RETURNTRANSFER => true,
]);
$audit = json_decode(curl_exec($ch), true);Sei endpoint, tutto il motore di audit
Ogni endpoint esegue lo stesso audit a 91 regole e gli stessi 11 moduli di punteggio di app.metricspot.com. JSON in ingresso, JSON in uscita. L'endpoint anonimo di prova non richiede chiavi; gli altri cinque accettano un token Bearer dalla tua dashboard.
/api/public/audit Audit anonimo
Lancia un audit SEO e di leggibilità per IA una tantum su qualsiasi URL pubblico. Restituisce punteggi su 11 moduli e 91 controlli, oltre a finding azionabili con link alla documentazione. Limitato a 1 audit per IP ogni 24 ore.
/api/audits Metti in coda un audit completo
Mette in coda un audit SEO e di leggibilità per IA completo. Include Core Web Vitals da Google PageSpeed Insights e traffico organico se GA4 e Google Search Console sono collegati. Risponde subito con audit_id e status: queued.
/api/audits/:id Recupera audit
Recupera tramite id un audit già messo in coda. Restituisce i punteggi degli 11 moduli (0-100), il punteggio totale, ogni finding con severità e testo di raccomandazione, oltre ai link ai report HTML e PDF.
/api/audits Elenca audit
Elenca gli audit dell'account, dai più recenti, deduplicati per URL. Restituisce audit_id, url, status, total_score, created_at. Limite predefinito 24, massimo 100. Paginazione standard con offset e limit.
/api/audits/:id/pdf Renderizza PDF brandizzato
Avvia il rendering di un PDF brandizzato per un audit. Combina con GET /api/pdfs/:id per ottenere l'URL firmato di download. Gli asset di brand (logo, colori, footer) vengono dalle impostazioni Brands; passa brand_id per scegliere un brand specifico.
/api/audits/:id/google Traffico organico
Restituisce lo snapshot a 28 giorni del traffico organico per un audit se GA4 e Google Search Console sono collegati all'URL auditato. Include sessioni, trend giornaliero, principali landing page, principali query e salute dell'indicizzazione.
API REST o server MCP: cosa si adatta al tuo stack
Entrambe le interfacce parlano con lo stesso motore di audit, con le stesse chiavi e gli stessi dati. Scegli REST quando scrivi HTTP puro da CI, script o tool no-code; scegli MCP quando un agente IA deve scoprire e concatenare strumenti da solo.
| Caso d'uso | Audit SEO manuale | Altre API SEO | MCP di MetricSpot | API REST di MetricSpot |
|---|---|---|---|---|
| CI/CD su ogni PR | Non fattibile al ritmo dei PR | Possibile ma costoso per chiamata, JSON fragile | Esagerato: MCP brilla con agenti interattivi, non con job headless | Un curl in una GitHub Action, commenta il delta di punteggio sulla PR |
| Tool no-code (Zapier, n8n, Make) | Export e copia-incolla manuali | Blocco HTTP su misura, campi mappati a mano, fragile ai cambi di schema | Oggi nessun supporto MCP nelle piattaforme no-code mainstream | Blocco HTTP standard con Bearer, risposta JSON che mappa pulita |
| Stack poliglotta (Go, Ruby, Java) | Non applicabile | Serve un SDK per linguaggio, spesso community-driven | Le librerie client MCP esistono soprattutto per TypeScript e Python | Qualsiasi linguaggio con client HTTPS funziona dal primo giorno |
| Job interni pianificati | Ore al mese, facili da saltare | Prezzo per chiamata, spesso per keyword o per dominio | Funziona, ma un sottoprocesso stdio è scomodo dentro cron | HTTPS puro da cron, Kubernetes CronJob o Lambda |
| Workflow con agenti IA | Umano in ogni loop | Gli agenti possono chiamare REST, ma servono wrapper scritti a mano | Pensato per questo: descrizioni e schemi scoperti automaticamente | Possibile, ma il codice di collegamento dell'agente lo scrivi tu |
| PDF brandizzato nel tuo SaaS | Export e rebrand manuali | Di solito solo nel piano più caro | Disponibile via get_audit_pdf, pensato per i flussi degli agenti | POST /api/audits/:id/pdf e poi GET /api/pdfs/:id, integra nella tua UI |
Prezzi dell'API REST
L'API REST è inclusa in ogni piano a pagamento di MetricSpot: stessi crediti di audit, stessi moduli, stesso rendering PDF. L'endpoint di audit anonimo è gratuito e funziona senza account. Le chiamate autenticate pesano sulla stessa quota mensile di audit che vedi nella tua dashboard. Le stesse chiavi ms_live_ funzionano per l'API REST e per il server MCP, senza quota separata.
Free
$0/mo
Prova la piattaforma. Senza carta, senza impegno.
- ·10 audit al mese (1 per sito ogni 24h)
- ·Tutti e dieci i moduli di punteggio
- ·Download PDF con il nostro brand
- ·Report multilingua
Starter
$29/mo
Per freelance con report mensili.
- ·Fino a 5 domini monitorati
- ·50 audit al mese
- ·Report PDF completamente white-label
- ·Brand kit personalizzato (logo, colore, footer)
Pro
$49/mo
Per agenzie, freelance e rivenditori.
- ·Tutto incluso in Starter
- ·Re-audit pianificati (settimanale, quindicinale o mensile)
- ·Domini monitorati illimitati
- ·Invio diretto dei report al cliente via email
Cosa costruiscono gli sviluppatori con l'API REST
Pattern concreti che vediamo nei team già in produzione con l'API. Ogni esempio usa gli stessi sei endpoint e lo stesso token Bearer.
- •CI/CD: audita ogni preview deploy all'apertura di una PR, pubblica un commento con il delta di punteggio rispetto a main, rompi la build se il punteggio cala di più di 5 punti.
- •Zapier, n8n, Make: avvia un audit quando arriva un nuovo lead nel tuo CRM, manda il punteggio totale e i 3 finding principali in un canale Slack, allega il PDF brandizzato.
- •Monitoraggio interno: pianifica un audit notturno dei tuoi 50 URL principali, invia i punteggi dei moduli a un pannello Grafana e alza un alert quando una categoria cala.
- •SaaS white-label: metti in coda un audit a richiesta dell'utente, renderizza il PDF brandizzato e incorpora i finding JSON nella tua UI senza ospitare il motore di audit.
- •Gate di QA: blocca un deploy se il modulo di leggibilità per IA scende sotto la soglia concordata con il cliente, con le regole fallite nel log di build.
- •Reportistica: chiama GET /api/audits/:id/google dopo ogni audit per consegnare un unico PDF che combina finding tecnici e traffico organico a 28 giorni.
Scrivere HTTP puro da uno script o da un runner CI è una via. Se guidi l'audit da un agente IA (Claude Code, Cursor, ChatGPT, Gemini), il nostro server MCP SEO espone gli stessi sei strumenti via Model Context Protocol con schemi scoperti automaticamente: stesso motore, stesse chiavi, niente codice di collegamento.
Domande frequenti
L'API REST è gratuita?
L'endpoint di audit anonimo (POST /api/public/audit) è gratuito e non richiede un account, limitato a 1 audit per IP ogni 24 ore. Gli endpoint autenticati sono inclusi in ogni piano MetricSpot, incluso il Free (10 audit al mese). Non c'è un prezzo separato per l'API né un sovrapprezzo per chiamata: le chiamate API pesano sulla stessa quota di audit che vedi nella dashboard.
Che differenza c'è con il server MCP?
Stesso motore di audit, stesse 91 regole, stessi 11 moduli, stesse chiavi Bearer. L'API REST è HTTP puro per chi scrive codice a mano: curl, fetch, requests, quel che vuoi. Il server MCP parla Model Context Protocol così gli agenti IA (Claude Code, Cursor, ChatGPT, Gemini) scoprono in automatico strumenti, schemi e auth. REST per CI, script e no-code; MCP per i flussi con agenti.
Posso usarla con tool no-code come Zapier?
Sì. Qualsiasi piattaforma no-code con un blocco HTTP generico funziona: Zapier (Webhooks by Zapier), n8n (HTTP Request node), Make (modulo HTTP), Pipedream, Retool. Imposta l'URL su https://app.metricspot.com/api/audits, metodo POST, aggiungi Authorization: Bearer ms_live_xxx negli header e invia {"url": "https://example.com"} come JSON. La risposta mappa pulita sui campi nativi di tutte le piattaforme testate.
Quali linguaggi hanno SDK ufficiali?
Nessuno per ora. Tutto quello che serve è un client HTTPS e il parsing JSON, e ogni linguaggio moderno lo ha di serie. Un SDK snello in JavaScript e TypeScript è in roadmap; nel frattempo i quattro esempi di codice sopra coprono circa il 90% delle integrazioni che vediamo. Se vuoi un SDK in un linguaggio specifico, apri una issue su github.com/MetricSpot.
Come mi autentico?
Invia Authorization: Bearer ms_live_xxx in ogni chiamata autenticata. I token hanno il prefisso ms_live_ e vengono mostrati una volta sola alla creazione; la dashboard conserva solo un hash. Trattali come ogni altro segreto: mai committarli, ruotali se vengono esposti, una chiave per integrazione così puoi revocare in modo mirato. La dashboard limita ogni account a 10 chiavi attive.
Da dove arrivano le chiavi API?
Generale su app.metricspot.com/settings/api-keys dopo esserti iscritto a un qualsiasi piano, incluso il Free. Ogni chiave viene mostrata una volta sola; copiala subito nel tuo secret store. Le stesse chiavi funzionano per l'API REST e per il server MCP di MetricSpot, quindi gestisci un solo set di credenziali per entrambe le vie di integrazione.
I dati sono gli stessi della dashboard MetricSpot?
Sì. Ogni endpoint passa per lo stesso motore di audit che alimenta app.metricspot.com: le stesse 91 regole su 11 moduli, le stesse severità, gli stessi testi di raccomandazione. Il PDF da POST /api/audits/:id/pdf è lo stesso che scarichi dalla dashboard. Il traffico organico arriva dalle stesse connessioni GA4 e Google Search Console che hai autorizzato nel tuo account.
Quali sono i rate limit?
L'endpoint anonimo è limitato a 1 audit per IP ogni 24 ore. Gli endpoint autenticati pesano sulla quota mensile del tuo piano: Free sono 10 al mese (1 per sito ogni 24 ore), Starter sono 50 al mese, Pro è illimitato. Non c'è un rate limit al secondo oltre a ciò che il pipeline di audit riesce ad assorbire; se metti in coda decine di richieste insieme vengono processate in ordine.
Basta scrivere report SEO a mano.
Lancia un audit, applica il tuo brand al PDF, invialo al cliente. In cinque minuti.
Avvia il tuo primo audit