POST /api/public/audit - Docs de MetricSpot

Què fa aquest endpoint

POST /api/public/audit executa una auditoria SEO síncrona sobre qualsevol URL pública sense clau d’API. Retorna el sobre complet d’auditoria a la mateixa resposta: puntuació total, puntuacions per mòdul i findings a nivell de regla. PageSpeed Insights es salta per mantenir la crida econòmica i la resposta per sota dels 60 segons.

Síncron: bloqueja fins que l’auditoria acaba, sense poll.
Anònim: identificat per IP del client, limitat a 1 auditoria per IP cada 24 hores.
Salta els Core Web Vitals (LCP, CLS, INP). Per a dades de PSI, utilitza el POST /api/audits autenticat.
El resultat no es persisteix a cap compte d’usuari: es desa una fila per al rate-limit a la taula d’auditories amb user_id = NULL.

Per què importa

L’auditoria anònima és el camí amb menys fricció per al widget de “auditoria gratuïta” de la home i per a eines de tercers que volen ensenyar la puntuació de MetricSpot abans de demanar a l’usuari que es registri. Sense OAuth, sense emissió de claus, sense pla: només un POST HTTPS.

Fluxos concrets:

Un constructor de landing pages incrusta un formulari “prova el teu lloc” que crida l’endpoint directament des del navegador de l’usuari i renderitza la puntuació en línia.
Un bot de Slack accepta /audit example.com des de qualsevol company i publica la puntuació sense que ningú del workspace s’hagi d’autenticar contra MetricSpot.

Com utilitzar-lo

Envia un POST amb un cos JSON que contingui url. La URL ha de ser absoluta (https://...), parsejable, i com a màxim de 2000 caràcters.

Petició

POST /api/public/audit HTTP/1.1
Host: app.metricspot.com
Content-Type: application/json

{ "url": "https://example.com" }

curl

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

Node fetch

const res = await fetch("https://app.metricspot.com/api/public/audit", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ url: "https://example.com" }),
});
const { audit } = await res.json();
console.log(`Score ${audit.total_score} for ${audit.domain}`);

Python httpx

import httpx

r = httpx.post(
    "https://app.metricspot.com/api/public/audit",
    json={"url": "https://example.com"},
    timeout=90.0,
)
print(r.json()["audit"]["total_score"])

Resposta

200 OK amb el sobre complet d’auditoria:

{
  "audit": {
    "url": "https://example.com",
    "domain": "example.com",
    "total_score": 78,
    "module_scores": {
      "technical": 92,
      "onpage": 71,
      "performance": null,
      "ai": 65,
      "modern_seo": 80,
      "social": 88,
      "accessibility": 74,
      "privacy": 82,
      "readability": 70,
      "tech_stack": 100,
      "organic_traffic": 100
    },
    "rules": [
      {
        "module": "onpage",
        "rule_id": "onpage.meta-description",
        "passed": false,
        "severity": "major",
        "title": "Missing meta description",
        "recommendation": "Add a 140-160 character meta description summarizing the page.",
        "data": {}
      }
    ]
  },
  "note": "Anonymous audits are limited and do not include Core Web Vitals. Sign up free for full audits and PDF reports."
}

Camps:

audit.url: la URL auditada, retornada tal qual.
audit.domain: hostname extret de la URL.
audit.total_score: puntuació ponderada entre tots els mòduls, 0 a 100.
audit.module_scores: puntuació per mòdul de 0 a 100, o null quan el mòdul s’ha saltat (p. ex. performance sempre és null per a auditories anònimes).
audit.rules: array de totes les regles avaluades. Cada entrada té module, rule_id, passed (boolean), severity (info | minor | major | critical), title, recommendation opcional i data (payload específic de la regla).
note: cadena que explica els límits anònims, per mostrar a la UI.

Sobre d’error

{ "error": "Rate limit reached", "message": "Sign up free for more reports." }

Errors habituals

Codi	Quan	Acció
`INVALID_URL` (400)	URL no parsejable, sense esquema, o > 2000 caràcters	Passa una URL absoluta `https://`
`RATE_LIMITED` (429)	La IP ja ha auditat en les darreres 24 hores	Espera 24h, o registra’t al pla Free (10 auditories/mes)
`UPSTREAM_FAILED` (502)	Falla puntual del rastrejador	Reintenta un cop amb un backoff curt
`INTERNAL` (500)	Error inesperat de backend	Reintenta; si persisteix, inicia sessió i utilitza `POST /api/audits` per a un reintent encuat

L’endpoint no retorna 401, 402 ni 404: és no autenticat per disseny i no té recursos que cercar.

Preguntes freqüents

Per què `performance` és sempre null?

L’endpoint anònim salta Google PageSpeed Insights per mantenir el temps total per sota dels 60 segons i evitar cremar la quota de PSI amb trànsit sense throttle. Per als Core Web Vitals (LCP, CLS, INP), utilitza el POST /api/audits autenticat, que executa PSI en paral·lel amb el rastrejador.

Com s’aplica el rate limit?

S’insereix una fila a la taula audits per cada execució anònima amb user_id = NULL i ip_address posat a la IP del client. Les crides següents des de la mateixa IP en 24 hores retornen 429. La IP es llegeix de les capçaleres estàndard del reverse proxy (X-Forwarded-For), de manera que auditories darrere d’un proxy compartit poden col·lidir.

Puc utilitzar-ho des del navegador?

Sí. L’endpoint configura CORS permissiu per a metricspot.com i accepta POSTs cross-origin. Per al teu propi domini, executa una funció serverless com a proxy prim: et permet afegir rate-limit per tenant i evita exposar les IPs dels teus visitants directament a MetricSpot.

Es persisteix el resultat enlloc?

Existeix una fila per a propòsits de rate-limit, però no està vinculada a cap compte d’usuari ni és visible en cap dashboard. Per desar i revisar una auditoria, registra’t gratis i crida POST /api/audits.