Inicio rápido de la API REST

Qué hace la API REST de MetricSpot

La API REST de MetricSpot es una interfaz JSON sobre HTTPS en app.metricspot.com que envuelve la misma tubería de auditoría que mueve el panel. Expone seis endpoints: lanzar una auditoría, obtenerla por id, listar auditorías recientes, generar un PDF con tu marca y consultar el tráfico orgánico desde Google Analytics 4 y Search Console vinculados.

Capacidades:

• Lanzar una auditoría anónima de un solo tiro para cualquier URL pública (sin clave, 1 por IP cada 24h).
• Encolar una auditoría completa de forma asíncrona y hacer polling hasta que termine.
• Obtener el envoltorio de una auditoría por id con puntuación, desglose por módulo y hallazgos.
• Listar auditorías recientes, deduplicadas por URL.
• Disparar la generación del PDF y descargar el fichero cuando esté listo.
• Leer un snapshot de 28 días de tráfico orgánico para cualquier auditoría, cacheado 24h.

La API es la misma superficie con la que habla el panel oficial. Todo lo que se ve en la UI, un cliente API puede reproducirlo.

Por qué importa

Una API REST convierte las auditorías en un bloque de construcción. Un bot CI puede auditar un preview deploy y romper el build si los hallazgos están en rojo. Un flujo de Zapier puede correr una auditoría semanal y publicar la puntuación en Slack. Una agencia puede sacar PDFs de 200 clientes en horario nocturno. Nada de esto exige automatización de navegador: solo HTTPS y un token Bearer.

Workflows concretos:

• Un bot de auditoría sobre PR llama a POST /api/audits cuando se despliega un preview, hace polling de GET /api/audits/:id hasta status === "completed" y publica el delta de puntuación en el PR.
• Un zap semanal llama a GET /api/audits para listar cada URL auditada este mes y manda un mensaje a Slack si alguna puntuación cae más de 5 puntos.
• Un cron de una agencia white-label saca POST /api/audits/:id/pdf por la noche para cada dominio de cliente y manda el PDF por email a la mañana siguiente.

Cómo usarla

Todos los endpoints salvo POST /api/public/audit requieren una clave API Bearer creada desde tu cuenta de MetricSpot. La auditoría anónima está limitada por IP y omite a propósito PageSpeed Insights para mantener el coste predecible.

Cabecera de autenticación:

Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Crea una clave en app.metricspot.com/settings/api-keys. Hasta 10 claves activas por cuenta. Las claves empiezan por ms_live_ y solo se muestran una vez al crearlas.

Endpoints

Método	Ruta	Auth	Límite
POST	/api/public/audit	ninguna	1 por IP cada 24h
POST	/api/audits	Bearer	Free 10/mes, Starter 50/mes, Pro ilimitado (más cooldown por dominio)
GET	/api/audits	Bearer	ninguno más allá del plan
GET	/api/audits/:id	Bearer	ninguno más allá del plan
POST	/api/audits/:id/pdf y luego GET /api/pdfs/:id	Bearer	ninguno más allá del plan
GET	/api/audits/:id/google	Bearer + Pro (GA4 / GSC vinculados)	ninguno; cacheado 24h

El catálogo legible por máquina está en /.well-known/api-catalog, según RFC 9727.

Inicio rápido: auditoría anónima (sin clave)

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

Inicio rápido: auditoría autenticada y polling

# 1. Encolar
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. Polling (sustituye 12345 por el audit_id devuelto)
curl https://app.metricspot.com/api/audits/12345 \
  -H "authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Inicio rápido: 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);

Inicio rápido: 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"])

Envoltorio de respuesta

Toda respuesta correcta es JSON. Los endpoints que crean recursos devuelven 201 Created con el recurso recién creado; los de lectura devuelven 200 OK con el recurso y los datos relacionados (findings, plan, cooldown) que el panel usa para pintar la misma vista.

Los errores son JSON con al menos error y un código HTTP; algunos endpoints añaden message para detalle legible por humanos.

Errores comunes

Código	Cuándo	Acción
UNAUTHORIZED (401)	Bearer ausente o inválido	Crea una clave en app.metricspot.com/settings/api-keys
FORBIDDEN (403)	Token válido pero sin permiso para el recurso (p. ej. auditoría de otra cuenta)	Usa la clave de la cuenta propietaria
RATE_LIMITED (429)	Tope por IP anónima o cooldown por dominio	Espera la ventana indicada
QUOTA_EXCEEDED (402)	Cupo mensual del plan agotado	Sube de plan en app.metricspot.com/billing
INVALID_URL (400)	URL inválida, no absoluta o de más de 2000 caracteres	Pasa una URL absoluta https://
AUDIT_NOT_FOUND (404)	audit_id no existe o no es tuyo	Lista tus auditorías para conseguir un id válido
UPSTREAM_FAILED (5xx)	Caída de PageSpeed Insights, GA4 o GSC	Reintenta con backoff

Preguntas frecuentes

¿Es gratis la API REST?

El endpoint anónimo (POST /api/public/audit) es gratis, limitado a 1 auditoría por IP cada 24h, y omite Core Web Vitals para mantener el coste acotado. Los cinco endpoints autenticados cuentan contra tu plan: Free 10 auditorías al mes, Starter 50, Pro ilimitado. Listar, obtener, PDF y tráfico orgánico no tienen coste extra por llamada.

¿Dónde está la especificación OpenAPI?

El catálogo legible por máquina vive en https://metricspot.com/.well-known/api-catalog, siguiendo RFC 9727. Enlaza la especificación JSON de cada endpoint y es lo primero que leen los agentes de descubrimiento.

¿Cuánto tarda una auditoría?

Entre 10 y 30 segundos en sitios típicos. Webs muy cargadas de JS o con muchísimos structured data pueden llegar a 90 segundos. PageSpeed Insights corre en paralelo con el crawler, así que el cuello de botella suele ser la respuesta de PSI de Google.

¿Puedo usar la API desde el navegador?

El endpoint anónimo admite CORS desde metricspot.com. Los autenticados no abren CORS por diseño: los tokens viven en servidor, nunca en JavaScript del cliente. Usa una función serverless o una ruta de backend como proxy.