API REST de SEO para desarrolladores

La API de SEO de MetricSpot lanza la misma auditoría de 154 reglas (SEO on-page + legibilidad para IA) que nuestro panel, por HTTP plano. Trae tu propio lenguaje: curl, Node, Python, PHP, cualquier cosa que hable HTTPS. Las mismas claves Bearer funcionan también con nuestro servidor MCP.

Prueba la API de SEO ahora mismo, sin registro, sin token, solo curl:

curl -s -X POST https://app.metricspot.com/api/public/audit \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' | jq .total_score

Sin tarjeta. Resultados en 30 segundos.

Prueba cada llamada desde tu navegador

Referencia OpenAPI 3.1 con ejemplos de petición en vivo para los 12 endpoints.

Abrir referencia de la API →

Autenticación con un token Bearer

Cada endpoint autenticado acepta un token en la cabecera Authorization: Authorization: Bearer ms_live_xxx. Genera una clave en app.metricspot.com/settings/api-keys (hasta 10 por cuenta). Las llamadas autenticadas con token requieren el plan Pro y consumen tu cuota de 5.000 al mes. El endpoint de auditoría anónima funciona sin clave, limitado a 1 auditoría por IP cada 24 horas. Las mismas claves ms_live_ funcionan tanto en esta API REST como en el servidor MCP de MetricSpot.

curl

Endpoint anónimo, sin token. Devuelve el sobre completo de auditoría en línea.

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

Node (fetch)

Funciona en Node 18+, Bun, Deno y navegadores modernos. Sin dependencias.

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 es equivalente: cambia httpx.post por 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

Extensión cURL estándar, disponible en cualquier instalación de PHP desde la 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);

Doce endpoints, todo el motor de auditoría

Cada endpoint ejecuta la misma auditoría de 154 reglas y los mismos 15 módulos de puntuación que app.metricspot.com. JSON entra, JSON sale. El endpoint de prueba anónima no requiere clave; los otros once aceptan un token Bearer de tu panel.

POST /api/public/audit
Sin auth

Auditoría anónima

Lanza una auditoría puntual de SEO y legibilidad para IA sobre cualquier URL pública. Devuelve puntuaciones en 15 módulos y 154 checks, más hallazgos accionables. Sin cuenta. Limitada a 1 auditoría por IP cada 24 horas.

POST /api/audits
Bearer requerido

Encolar auditoría completa

Encola una auditoría completa de SEO y legibilidad para IA. Incluye Core Web Vitals desde Google PageSpeed Insights y tráfico orgánico si tienes GA4 y Google Search Console conectados. Responde al instante con audit_id y status: queued.

GET /api/audits/:id
Bearer requerido

Obtener auditoría

Recupera por id una auditoría ya encolada. Devuelve las puntuaciones de los 15 módulos (0-100), la puntuación total, cada hallazgo con severidad y texto de recomendación, y los enlaces a los informes HTML y PDF.

GET /api/audits
Bearer requerido

Listar auditorías

Lista las auditorías de la cuenta, más recientes primero, deduplicadas por URL. Devuelve audit_id, url, status, total_score, has_ga, has_gsc y created_at. Límite por defecto 24, máximo 100.

DELETE /api/audits/:id
Bearer requerido

Borrar auditorías por URL

Borra todas las auditorías que coincidan con la URL del audit_id indicado. Devuelve 204 al completarse.

PATCH /api/audits/reorder
Bearer requerido

Reordenar auditorías

Fija la posición de las auditorías en el dashboard. Body: { "url_order": ["https://a.com", "https://b.com", ...] } (máximo 200 URLs). Devuelve 204.

GET /api/audits/history
Bearer requerido

Histórico de auditorías

Devuelve hasta 50 auditorías históricas para una URL. Útil para seguir la evolución de la puntuación. Query: ?url=<url-codificada>.

GET /api/audits/usage
Bearer requerido

Consumo de auditorías

Devuelve la cuota del mes en curso: audits_remaining, audits_used, plan_limit y reset_at.

POST /api/audits/:id/pdf
Bearer requerido

Renderizar PDF con marca

Lanza el render de un PDF con marca para una auditoría completada. Body: { "language": "en", "brand_id": 42 } (ambos opcionales). Devuelve 201 con { pdf: { id, status: "pending" } }. Combínalo con GET /api/pdfs/:id para sondear el estado.

GET /api/pdfs/:id
Bearer requerido

Sondear estado del PDF

Devuelve { pdf: { id, status, download_url } }. Si la cabecera Accept es application/pdf y el estado es ready, devuelve directamente el binario del PDF.

GET /api/pdfs/:id/download
Bearer requerido

Descargar PDF

Descarga directa de un PDF completado con Content-Disposition: attachment.

GET /api/audits/:id/report
Bearer requerido

Previsualizar informe HTML

Renderiza el informe de auditoría como HTML con marca (la misma plantilla a partir de la que se genera el PDF). Útil para embeber en un iframe de portal de cliente antes de descargar el PDF. Query: ?lang=en&brand_id=42.

API REST o servidor MCP: cuál encaja con tu stack

Ambas interfaces hablan con el mismo motor de auditoría, con las mismas claves y los mismos datos. Elige REST si escribes HTTP plano desde CI, scripts o herramientas no-code; elige MCP si un agente de IA necesita descubrir y encadenar herramientas por su cuenta.

Caso de uso Auditoría SEO manual Otras APIs de SEO MCP de MetricSpot API REST de MetricSpot
CI/CD en cada PR No es viable a ritmo de PR Posible pero caro por llamada, JSON quebradizo Excesivo: MCP brilla con agentes interactivos, no con jobs headless Un curl en un GitHub Action, comenta el delta de puntuación en el PR
Herramientas no-code (Zapier, n8n, Make) Exportación y copiar y pegar manuales Bloque HTTP a medida, campos mapeados a mano, frágil ante cambios de esquema Sin soporte MCP en plataformas no-code mayoritarias hoy Bloque HTTP estándar con Bearer, respuesta JSON que mapea limpiamente
Stack polígloto (Go, Ruby, Java) No aplicable Hace falta un SDK por lenguaje, a menudo mantenido por la comunidad Las librerías cliente MCP existen sobre todo para TypeScript y Python Cualquier lenguaje con cliente HTTPS funciona desde el primer día
Jobs internos programados Horas al mes, fáciles de saltarse Pricing por llamada, a menudo por keyword o por dominio Funciona, pero un subproceso stdio es incómodo dentro de cron HTTPS plano desde cron, Kubernetes CronJob o Lambda
Flujos con agentes de IA Humano en cada bucle Los agentes pueden llamar a REST, pero necesitan wrappers escritos a mano Pensado para esto: descripciones y esquemas auto-descubiertos Posible, pero escribirás tú mismo el código de pegamento del agente
PDF con marca en tu SaaS Exportación y rebrand manuales Normalmente solo en el plan más caro Disponible vía get_audit_pdf, diseñado para flujos de agente POST /api/audits/:id/pdf y luego GET /api/pdfs/:id, embébelo en tu UI

Cómo se compara la API de SEO de MetricSpot con DataForSEO y Serpstack

DataForSEO es un mercado completo de datos SEO; Serpstack es una API de scraping de SERPs; MetricSpot es una API enfocada en auditoría on-page + legibilidad para IA. Mismo trío de letras, forma de valor distinta. Elige la que coincida con el trabajo que estás haciendo.

Qué comparas DataForSEO Serpstack API de SEO de MetricSpot
Trabajo principal que resuelve Marketplace masivo de datos: SERPs, keywords, backlinks, on-page Hace scraping del HTML de las SERPs de Google bajo demanda Lanza una auditoría completa on-page + legibilidad para IA sobre una URL, devuelve scores y correcciones
Qué obtienes de una llamada JSON específico por endpoint; la auditoría on-page devuelve ~30 etiquetas/problemas Resultados orgánicos, anuncios, consultas relacionadas, sin evaluación on-page Score total, 15 módulos (0-100), cada hallazgo de las 154 reglas, severidad y texto de recomendación
Modelo de precios Por llamada, varía por endpoint ($0,0006-$0,002 cada una), saldo prepago Mensual por tramos: 100 gratis / $30 por 5K / hasta $200 por 50K SERPs Plano $49/mes Pro = 5.000 llamadas API, sin matemáticas por llamada
Endpoint de prueba anónimo No, requiere registro + depósito de $1 100 llamadas/mes gratis con registro + clave de acceso Sí, 1 auditoría/IP/24h sin ningún registro, JSON completo
Comprobaciones de legibilidad para IA / era LLM No están en el módulo on-page No aplica (solo SERPs) Módulo dedicado: llms.txt, schema para IA, contenido apto para citas, claridad semántica
PDF con marca blanca No disponible No disponible POST /api/audits/:id/pdf devuelve un PDF con tu logo y colores
Servidor MCP para agentes IA No hay MCP oficial No hay MCP oficial Sí, mismas claves Bearer, mismo motor de auditoría, compatible con Claude Code, Cursor y ChatGPT
Estilo de autenticación HTTP Basic con login + contraseña (menos común en stacks modernos) Clave API en la query string (?access_key=…) Cabecera estándar Authorization: Bearer ms_live_xxx

Precios de la API REST

La API REST está incluida en Pro 49 $/mes. Las cuentas Pro tienen 5.000 llamadas API al mes contra cualquiera de los doce endpoints autenticados con token. El endpoint de auditoría anónima es gratis para todos (limitado a 1 por IP cada 24 h). Las cuentas Free y Starter pueden consultar la documentación y crear tokens, pero las llamadas autenticadas con token devuelven 403 hasta que pasen a Pro. Las mismas claves ms_live_ funcionan tanto para esta API REST como para el servidor MCP de MetricSpot, contra la misma cuota mensual compartida.

Free

$0/mo

Prueba la plataforma. Sin tarjeta, sin compromiso.

  • ·10 auditorías al mes (1 por sitio cada 24h)
  • ·Los diez módulos de puntuación
  • ·Descarga PDF con nuestra marca
  • ·Informes multilingües

Starter

$29/mo

Para freelancers con informes mensuales.

  • ·Hasta 5 dominios en seguimiento
  • ·50 auditorías al mes
  • ·Informes PDF con marca blanca completa
  • ·Kit de marca personalizado (logo, color, pie)

Pro

$49/mo

Para agencias, freelancers y revendedores.

  • ·Todo lo de Starter
  • ·Re-auditorías programadas (semanal, quincenal o mensual)
  • ·Informes comparativos de competidores (hasta 3 competidores)
  • ·Dominios en seguimiento ilimitados

Ver límites y precios de los planes →

Qué construyen los desarrolladores con la API REST

Patrones concretos que vemos en equipos que ya están en producción con la API. Cada ejemplo usa las mismas herramientas y el mismo token Bearer.

  • •CI/CD: audita cada preview deploy al abrir un PR, comenta el delta de puntuación frente a main y rompe el build si la puntuación cae más de 5 puntos.
  • •Zapier, n8n, Make: lanza una auditoría cuando entra un lead nuevo en tu CRM, manda la puntuación total y los 3 hallazgos principales a un canal de Slack y adjunta el PDF con tu marca.
  • •Monitorización interna: programa una auditoría nocturna de tus 50 URLs principales, vuelca las puntuaciones de los módulos en un panel de Grafana y alerta cuando cae una categoría.
  • •SaaS con marca blanca: encola una auditoría a demanda del usuario, renderiza el PDF con tu marca y embebe los hallazgos JSON en tu propia UI sin alojar el motor de auditoría.
  • •Gates de QA: bloquea un deploy si el módulo de legibilidad para IA baja del umbral comprometido con tu cliente, con las reglas fallidas en el log del build.
  • •Reportes: lanza GET /api/audits/history?url= después de cada auditoría para enviar una gráfica de evolución de la puntuación en el tiempo junto con el último PDF con tu marca.

Escribir HTTP plano desde un script o un runner de CI es un camino. Si conduces la auditoría desde un agente de IA (Claude Code, Cursor, ChatGPT, Gemini), nuestro servidor MCP de SEO expone las mismas herramientas sobre Model Context Protocol con esquemas auto-descubiertos: mismo motor, mismas claves, sin código de pegamento.

Preguntas frecuentes

¿La API REST es gratis?

El endpoint de auditoría anónima (POST /api/public/audit) es gratuito y no requiere cuenta, limitado a 1 auditoría por IP cada 24 horas. Los once endpoints autenticados con token requieren el plan Pro a 49 $/mes, que incluye 5.000 llamadas API al mes sin coste adicional.

¿En qué se diferencia esto del servidor MCP?

Mismo motor de auditoría, mismas 154 reglas en 15 módulos, mismas claves Bearer. La API REST es HTTP plano para personas que escriben código: curl, fetch, requests, lo que sea. El servidor MCP habla Model Context Protocol para que los agentes de IA (Claude Code, Cursor, ChatGPT, Gemini) descubran automáticamente herramientas, esquemas y autenticación. Usa REST para CI, scripts y no-code; usa MCP para flujos con agentes.

¿Puedo usarla con herramientas no-code como Zapier?

Sí. Cualquier plataforma no-code con un bloque HTTP genérico funciona: Zapier (Webhooks by Zapier), n8n (HTTP Request node), Make (módulo HTTP), Pipedream, Retool. Pon la URL en https://app.metricspot.com/api/audits, método POST, añade Authorization: Bearer ms_live_xxx a las cabeceras y envía {"url": "https://example.com"} como JSON. La respuesta mapea limpiamente a campos nativos en todas las plataformas probadas.

¿Qué lenguajes tienen SDK oficial?

Ninguno todavía. Lo único necesario es un cliente HTTPS y parsing de JSON, que cualquier lenguaje moderno trae de serie. Un SDK fino de JavaScript y TypeScript está en el roadmap; hasta entonces, los cuatro ejemplos de código de arriba cubren el 90% de las integraciones que vemos. Si quieres un SDK en un lenguaje concreto, abre una issue en github.com/MetricSpot.

¿Cómo me autentico?

Envía Authorization: Bearer ms_live_xxx en cada llamada autenticada. Los tokens llevan el prefijo ms_live_ y se muestran una sola vez al crearlos; el panel guarda solo un hash. Trátalos como cualquier otro secreto: nunca los subas a git, rótalos si los expones, usa una clave por integración para poder revocarlas individualmente. El panel limita cada cuenta a 10 claves activas.

¿De dónde salen las claves API?

Genéralas en app.metricspot.com/settings/api-keys tras registrarte en cualquier plan, incluido el Free. Cada clave se muestra una sola vez; cópiala a tu gestor de secretos al instante. Las mismas claves funcionan en la API REST y en el servidor MCP de MetricSpot, así que solo gestionas un conjunto de credenciales en los dos caminos de integración.

¿Los datos son los mismos que en el panel de MetricSpot?

Sí. Cada endpoint pasa por el mismo motor de auditoría que mueve app.metricspot.com: las mismas 154 reglas en 15 módulos, las mismas severidades, los mismos textos de recomendación. El PDF de POST /api/audits/:id/pdf es el mismo que descargas desde el panel.

¿Cuáles son los límites de uso?

El endpoint anónimo está limitado a 1 auditoría por IP cada 24 horas. El acceso a la API requiere Pro 49 $/mes. Pro incluye 5.000 llamadas API al mes. Free y Starter no incluyen acceso a la API. El endpoint anónimo sigue siendo gratuito (1 por IP cada 24 h).

¿Qué pasa si supero las 5.000 llamadas en un mes?

El endpoint devuelve HTTP 429 con cuerpo { error: "quota_exceeded", used: 5000, limit: 5000 }. La cuota se reinicia al comienzo del siguiente mes natural. Si necesitas una cuota mayor, contáctanos desde el formulario de soporte y acordamos un tramo personalizado.

Deja de escribir informes SEO a mano.

Ejecuta una auditoría, pon tu marca al PDF, envíalo. En cinco minutos.

Empieza tu primera auditoría