Inici ràpid de l'API REST - Docs de MetricSpot

Què fa l’API REST de MetricSpot

L’API REST de MetricSpot és una interfície JSON sobre HTTPS a app.metricspot.com que embolcalla la mateixa cadena d’auditoria que mou el dashboard. Exposa sis endpoints: executar una auditoria, obtenir-ne una per id, llistar les auditories recents, generar un PDF amb marca i obtenir tràfic orgànic de propietats vinculades de Google Analytics 4 i Search Console.

Capacitats:

Executar una auditoria anònima d’un sol cop sobre qualsevol URL pública (sense auth, 1 per IP cada 24 hores).
Encuar una auditoria completa de forma asíncrona i fer poll fins que acabi.
Obtenir un sobre d’auditoria per id amb puntuació, desglossament per mòdul i findings.
Llistar les auditories recents, deduplicades per URL.
Disparar la generació del PDF i descarregar-ne el fitxer quan estigui llest.
Llegir una instantània de tràfic orgànic de 28 dies per a qualsevol auditoria, amb cache de 24 hores.

L’API és la mateixa superfície que utilitza el propi dashboard de MetricSpot. Tot el que veus a la UI ho pot reproduir un client de l’API.

Per què importa

Una API REST converteix les auditories en un component reutilitzable. Un bot de CI pot auditar un deploy de preview i fer fallar la build quan hi ha findings en vermell. Un flux de Zapier pot executar una auditoria setmanal i publicar la puntuació a Slack. Una agència pot generar PDFs per a 200 clients de forma programada. Cap d’aquests fluxos necessita automatització de navegador: només HTTPS i un token Bearer.

Fluxos concrets:

Un bot d’auditoria a les PR crida POST /api/audits quan es desplega una URL de preview, fa poll a GET /api/audits/:id fins que status === "completed" i publica la diferència de puntuació a la PR.
Un zap setmanal de Zapier crida GET /api/audits per llistar totes les URL auditades aquest mes i dispara un missatge a Slack si alguna puntuació ha caigut més de 5 punts.
Un cron d’agència white-label crida POST /api/audits/:id/pdf durant la nit per a cada domini de client i envia el PDF renderitzat l’endemà al matí.

Com utilitzar-la

Tots els endpoints excepte POST /api/public/audit requereixen una clau d’API Bearer emesa des del teu compte de MetricSpot. L’auditoria anònima està limitada per IP i salta intencionadament PageSpeed Insights per mantenir el cost predictible.

Capçalera d’auth:

Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Emet una clau a app.metricspot.com/settings/api-keys. Fins a 10 claus actives per compte. Les claus comencen per ms_live_ i només es mostren un cop, en crear-les.

Endpoints

Mètode	Path	Auth	Límit
`POST`	`/api/public/audit`	cap	1 per IP cada 24 hores
`POST`	`/api/audits`	Bearer	Free 10/mes, Starter 50/mes, Pro il·limitat (més cooldown per domini)
`GET`	`/api/audits`	Bearer	cap més enllà del pla
`GET`	`/api/audits/:id`	Bearer	cap més enllà del pla
`POST`	`/api/audits/:id/pdf` + `GET /api/pdfs/:id`	Bearer	cap més enllà del pla
`GET`	`/api/audits/:id/google`	Bearer + Pro (GA4 / GSC vinculats)	cap més enllà del pla, cache 24h

El catàleg complet llegible per màquines viu a /.well-known/api-catalog segons la RFC 9727.

Inici ràpid: auditoria anònima (sense clau)

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

Inici ràpid: auditoria autenticada + poll

# 1. Encuar
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. Fer poll (substitueix 12345 per l'audit_id retornat)
curl https://app.metricspot.com/api/audits/12345 \
  -H "authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Inici ràpid: 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);

Inici ràpid: 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"])

Sobre de resposta

Tota resposta correcta és JSON. Els endpoints que modifiquen retornen 201 Created amb el recurs creat; els endpoints de lectura retornen 200 OK amb el recurs i qualsevol dada relacionada (findings, pla, cooldown) que el dashboard fa servir per renderitzar la mateixa vista.

Els errors són JSON amb com a mínim el camp error i un codi d’estat HTTP; alguns endpoints afegeixen message amb detall llegible.

Errors habituals

Codi	Quan	Acció
`UNAUTHORIZED` (401)	Token Bearer absent o invàlid	Emet una clau a `app.metricspot.com/settings/api-keys`
`FORBIDDEN` (403)	Token vàlid però no autoritzat per a aquest recurs (p. ex. auditoria d’un altre usuari)	Utilitza una clau del compte propietari
`RATE_LIMITED` (429)	Límit d’IP anònima o cooldown per domini	Espera la finestra indicada
`QUOTA_EXCEEDED` (402)	Allocació mensual del pla exhaurida	Actualitza a `app.metricspot.com/billing`
`INVALID_URL` (400)	URL no parsejable, no absoluta, o més llarga de 2000 caràcters	Passa una URL absoluta `https://`
`AUDIT_NOT_FOUND` (404)	`audit_id` no existeix o no és teu	Llista les auditories per trobar un id vàlid
`UPSTREAM_FAILED` (5xx)	Falla puntual de PageSpeed Insights, GA4 o GSC	Reintenta amb backoff

Preguntes freqüents

És gratuïta l’API REST?

L’endpoint anònim (POST /api/public/audit) és gratuït, limitat a 1 auditoria per IP cada 24 hores, i salta els Core Web Vitals per mantenir el cost predictible. Els cinc endpoints autenticats compten contra el teu pla: Free 10 auditories al mes, Starter 50, Pro il·limitat. Els endpoints de llistar, get, PDF i tràfic orgànic no tenen cost per crida més enllà de l’auditoria que referencien.

On és l’especificació OpenAPI?

El catàleg llegible per màquines és a https://metricspot.com/.well-known/api-catalog segons la RFC 9727. Enllaça la spec JSON de cada endpoint i és el primer que llegeixen els agents de discovery.

Quant triga una auditoria?

10 a 30 segons per a llocs típics. Objectius amb molt JS o llocs amb grans quantitats de dades estructurades poden trigar fins a 90 segons. PageSpeed Insights es consulta en paral·lel amb el rastrejador, així que el coll d’ampolla acostuma a ser el temps de resposta del PSI de Google.

Puc utilitzar l’API des del navegador?

L’endpoint anònim accepta CORS des de metricspot.com. Els endpoints autenticats no configuren CORS permissiu de forma deliberada: els tokens van al servidor, mai al JavaScript del client. Utilitza una funció serverless o una ruta de backend com a proxy.