Avvio rapido API REST

Cosa fa l’API REST di MetricSpot

L’API REST di MetricSpot è un’interfaccia JSON su HTTPS a app.metricspot.com che incapsula la stessa pipeline di audit che alimenta la dashboard. Espone sei endpoint: lanciare un audit, recuperarne uno per id, elencare gli audit recenti, generare un PDF brandizzato, e leggere il traffico organico dalle proprietà Google Analytics 4 e Search Console collegate.

Capacità:

• Lanciare un audit anonimo one-shot su qualsiasi URL pubblico (senza auth, 1 per IP ogni 24h).
• Mettere in coda un audit completo in modo asincrono e fare polling fino al completamento.
• Recuperare la busta di un audit per id con punteggio, ripartizione per modulo e findings.
• Elencare gli audit recenti, deduplicati per URL.
• Avviare la generazione PDF e fare streaming del file una volta pronto.
• Leggere uno snapshot a 28 giorni del traffico organico per qualsiasi audit, con cache 24h.

L’API è la stessa superficie con cui parla la dashboard ufficiale. Tutto ciò che vedi nell’UI, un client API può riprodurlo.

Perché è importante

Un’API REST trasforma gli audit in un mattone costruttivo. Un bot CI può auditare un preview deploy e far fallire la build su finding rossi. Un flusso Zapier può lanciare un audit settimanale e postare il punteggio su Slack. Un’agenzia di reporting può tirare PDF per 200 clienti su una pianificazione. Nessuno di questi casi richiede automazione browser: solo HTTPS e un token Bearer.

Flussi concreti:

• Un bot audit-on-PR chiama POST /api/audits quando un preview URL viene deployato, polla GET /api/audits/:id fino a status === "completed", e posta il delta di punteggio sul PR.
• Uno zap settimanale chiama GET /api/audits per elencare ogni URL auditato questo mese, e fa scattare un messaggio Slack se qualche punteggio è calato di più di 5 punti.
• Un cron di agenzia white-label tira POST /api/audits/:id/pdf durante la notte per ogni dominio cliente e invia il PDF renderizzato per email il mattino dopo.

Come usarla

Tutti gli endpoint tranne POST /api/public/audit richiedono una chiave API Bearer generata dal tuo account MetricSpot. L’audit anonimo è limitato per IP e salta intenzionalmente PageSpeed Insights per mantenere il costo prevedibile.

Header di autenticazione:

Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Genera una chiave su app.metricspot.com/settings/api-keys. Fino a 10 chiavi attive per account. Le chiavi iniziano con ms_live_ e sono mostrate una sola volta alla creazione.

Endpoint

Metodo	Percorso	Auth	Limite
POST	/api/public/audit	nessuna	1 per IP ogni 24h
POST	/api/audits	Bearer	Free 10/mese, Starter 50/mese, Pro illimitato (più cooldown per dominio)
GET	/api/audits	Bearer	nessuna oltre il piano
GET	/api/audits/:id	Bearer	nessuna oltre il piano
POST	/api/audits/:id/pdf poi GET /api/pdfs/:id	Bearer	nessuna oltre il piano
GET	/api/audits/:id/google	Bearer + Pro (GA4 / GSC collegati)	nessuna, cache 24h

Il catalogo leggibile a macchina è a /.well-known/api-catalog per RFC 9727.

Avvio rapido: audit anonimo (senza chiave)

curl -X POST https://app.metricspot.com/api/public/audit \
  -H "content-type: application/json" \
  -d '{"url": "https://example.com"}'

Avvio rapido: audit autenticato + polling

# 1. Mettere in coda
curl -X POST https://app.metricspot.com/api/audits \
  -H "authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -d '{"url": "https://example.com"}'

# 2. Pollare (sostituisci 12345 con l'audit_id restituito)
curl https://app.metricspot.com/api/audits/12345 \
  -H "authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Avvio rapido: Node fetch

const res = await fetch("https://app.metricspot.com/api/audits", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  },
  body: JSON.stringify({ url: "https://example.com" }),
});
const { audit } = await res.json();
console.log(audit.id, audit.status);

Avvio rapido: Python httpx

import httpx

r = httpx.post(
    "https://app.metricspot.com/api/audits",
    headers={"authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={"url": "https://example.com"},
    timeout=30.0,
)
print(r.json()["audit"])

Busta di risposta

Ogni risposta riuscita è JSON. Gli endpoint mutanti restituiscono 201 Created con la risorsa creata; gli endpoint di lettura restituiscono 200 OK con la risorsa e i dati correlati (findings, plan, cooldown) che la dashboard usa per renderizzare la stessa vista.

Gli errori sono JSON con almeno error e codice HTTP; alcuni endpoint aggiungono message per dettaglio leggibile.

Errori comuni

Codice	Quando	Azione
UNAUTHORIZED (401)	Bearer mancante o non valido	Genera una chiave su app.metricspot.com/settings/api-keys
FORBIDDEN (403)	Token valido ma senza permesso per questa risorsa (audit di un altro)	Usa la chiave dell’account proprietario
RATE_LIMITED (429)	Tetto IP anonimo o cooldown per dominio	Aspetta la finestra indicata
QUOTA_EXCEEDED (402)	Quota mensile del piano esaurita	Upgrade su app.metricspot.com/billing
INVALID_URL (400)	URL non parsabile, non assoluto, o > 2000 caratteri	Passa un URL assoluto https://
AUDIT_NOT_FOUND (404)	audit_id inesistente o non tuo	Elenca i tuoi audit per ottenere un id valido
UPSTREAM_FAILED (5xx)	Glitch PageSpeed Insights, GA4 o GSC	Riprova con backoff

Domande frequenti

L’API REST è gratuita?

L’endpoint anonimo (POST /api/public/audit) è gratuito, limitato a 1 audit per IP ogni 24h, e salta Core Web Vitals per mantenere il costo prevedibile. I cinque endpoint autenticati contano contro il tuo piano: Free 10 audit al mese, Starter 50, Pro illimitato. Elencare, ottenere, PDF e traffico organico non hanno costo aggiuntivo per chiamata.

Dov’è la spec OpenAPI?

Il catalogo leggibile a macchina è a https://metricspot.com/.well-known/api-catalog per RFC 9727. Collega la spec JSON di ogni endpoint ed è ciò che leggono per primi gli agenti di discovery.

Quanto dura un audit?

10 a 30 secondi sui siti tipici. Target ricchi di JS o siti con molti structured data possono richiedere fino a 90 secondi. PageSpeed Insights gira in parallelo al crawler, quindi il collo di bottiglia è di solito la risposta PSI di Google.

Posso usare l’API dal browser?

L’endpoint anonimo accetta CORS da metricspot.com. Gli endpoint autenticati non impostano CORS permissivo per design: i token vivono lato server, mai nel JavaScript client. Usa una funzione serverless o una route backend come proxy.