OLAB Assist Iniciar sesión
Desarrolladores

API, webhooks y MCP

Lleva los datos de monitoreo de OLAB Assist a las herramientas que tu agencia ya usa. Versión 1, de solo lectura, incluida en el plan Agency.

Resumen

OLAB Assist ofrece a las agencias cinco formas de usar sus datos de monitoreo fuera del panel. Todas leen los mismos datos y siguen el mismo contrato versionado, así que lo que ves en una coincide con las demás.

  • API REST: lleva sitios, puntuaciones, hallazgos, respuestas de IA, historial de puntuación, tendencias y cambios a un CRM, un almacén de datos o una herramienta de informes.
  • Webhooks: recibe un evento JSON firmado en cuanto termina un escaneo o llegan nuevas respuestas de IA, sin necesidad de consultar continuamente.
  • Servidor MCP: conecta Claude, ChatGPT, Cursor o cualquier cliente de Model Context Protocol y pregunta por tus sitios en lenguaje natural.
  • Looker Studio: crea informes para clientes sobre puntuaciones, problemas y visibilidad en IA con el conector de OLAB Assist.
  • Notion: mantén al día una página de Notion con tus sitios, problemas y respuestas de IA, sin código.

¿Prefieres una guía? Las guías de integración configuran cada una paso a paso: Notion, Looker Studio, Slack, Discord, Zapier y Make, API REST y MCP.

La API, los webhooks, MCP, Looker Studio y Notion están incluidos en el plan Agency. El propietario de la cuenta gestiona las claves y los webhooks en Integraciones.

Autenticación

Crea una clave en la página de Integraciones. La clave completa se muestra una sola vez; solo guardamos un hash. Envíala en cada solicitud:

curl https://api.olabassist.com/api/v1/sites \
  -H "Authorization: Bearer olab_YOUR_KEY"

Las claves son de solo lectura y están limitadas a tu espacio de trabajo: una clave solo ve los sitios de la cuenta que la creó. Si revocas una clave en la página de Integraciones, deja de funcionar al instante. Si la cuenta deja el plan Agency, sus claves dejan de funcionar hasta que vuelva.

Solicitudes y límites

  • URL base: https://api.olabassist.com/api/v1. GET /api/v1 devuelve la lista de endpoints.
  • Todos los endpoints usan GET y devuelven JSON: { "data": …, "api_version": "v1" }. Las listas paginadas también devuelven next_cursor.
  • Las marcas de tiempo están en ISO 8601 y UTC. Las puntuaciones van de 0 a 100.
  • Límite de uso: 120 solicitudes por minuto por clave. Por encima recibes 429 con retryAfterSeconds.
  • Donde la ruta incluya {site} puedes usar el id del sitio o su dominio, p. ej. /sites/example.com.

Endpoints

GET /account

Tu plan, límites y uso.

GET /sites

Todos los sitios monitoreados con su última puntuación y sus problemas abiertos.

{
  "data": [{
    "id": "k3Jd9x2Lq",
    "domain": "example.com",
    "brand_name": "Example",
    "status": "active",
    "created_at": "2026-09-01T10:00:00.000Z",
    "next_scan_at": "2026-10-12T10:00:00.000Z",
    "last_checked_at": "2026-10-05T10:00:00.000Z",
    "score": { "overall": 92, "seo": 95, "geo": 88, "aeo": 90, "aio": 94 },
    "issues": { "critical": 0, "warnings": 2 },
    "regressions_last_7_days": 0,
    "report_url": "https://olabassist.com/r/…",
    "app_url": "https://olabassist.com/app/?site=k3Jd9x2Lq"
  }],
  "api_version": "v1"
}

GET /sites/{site}

Todo lo anterior más ai_visibility (respuestas revisadas, cuántas te mencionaron, cuántas citaron tu sitio, tu posición entre las marcas seguidas, tono), share_of_voice por marca seguida, top_sources que citan los asistentes, competitors, questions y engines.

GET /sites/{site}/findings?status=fail,warn

Comprobaciones del último escaneo con su evidencia y la solución (summary, where y code listo para pegar cuando lo hay). Sin status se devuelven todas las comprobaciones.

GET /sites/{site}/answers

Respuestas de IA guardadas, de la más reciente a la más antigua. Cada respuesta incluye la pregunta, el asistente (engine), si tu marca fue mencionada (named) y citada (cited), su posición (rank), el tono (sentiment), todas las marcas seguidas en la respuesta y las fuentes citadas.

Parámetros: engine, question_id, since (fecha ISO), limit (1–500, por defecto 100), cursor, include_answer=true para el texto completo. Si next_cursor no es nulo, envíalo como cursor para obtener la página siguiente.

GET /sites/{site}/history

La puntuación tras cada escaneo, de la más antigua a la más reciente (limit hasta 200).

GET /sites/{site}/trends

Series temporales para gráficos e informes, agrupadas por day (día), week (semana desde el lunes) o month (mes, UTC). Parámetros: from y to (AAAA-MM-DD, inclusive; por defecto los últimos 90 días, hasta dos años), bucket (por defecto según el rango). La respuesta incluye periods (fechas de inicio de cada periodo), series (un arreglo por métrica alineado con periods, null donde no hay datos), un catalog que describe cada serie (unit: score, pct, count o rank; better: up o down) y los changes del rango.

Series: score.overall, score.seo, score.geo, score.aeo, score.aio (último escaneo de cada periodo), issues.fail, issues.warn, ai.visibility, ai.cited, ai.positive, ai.negative (porcentajes), ai.position (posición media cuando te mencionan), ai.answers, engine.<asistente> e intent.<intención> (visibilidad %) y brand.<dominio del competidor> (porcentaje de respuestas que mencionan a ese competidor).

GET /sites/{site}/changes

Qué cambió entre escaneos: problemas new (nuevos), lo que empeoró (worse) y lo que mejoró (better, resuelto). Parámetros: since, limit.

Errores

Los errores usan códigos de estado HTTP y un cuerpo JSON: { "error": "NOT_FOUND", "message": "…" }.

  • 401 clave ausente, no válida o revocada
  • 403 API_NOT_IN_PLAN el espacio de trabajo no está en el plan Agency
  • 404 el sitio no está en este espacio de trabajo
  • 405 la API es de solo lectura
  • 429 límite de uso superado

Webhooks

Añade una dirección https en la página de Integraciones y elige los eventos que quieres recibir. Cada evento se envía como un POST con cuerpo JSON:

{
  "id": "evt_4Hh2…",
  "type": "scan.completed",
  "api_version": "v1",
  "created_at": "2026-10-05T10:00:00.000Z",
  "data": {
    "site": { "id": "k3Jd9x2Lq", "domain": "example.com", "app_url": "…" },
    "audit_id": "…",
    "checked_at": "2026-10-05T10:00:00.000Z",
    "score": { "overall": 92, "seo": 95, "geo": 88, "aeo": 90, "aio": 94 },
    "issues": { "critical": 0, "warnings": 2 },
    "changes": [{ "finding_id": "seo-title", "kind": "worse", "from": "pass", "to": "warn", "title": "Title tag is too long", "at": "…" }],
    "report_url": "https://olabassist.com/r/…"
  }
}

Eventos

  • score.dropped: la puntuación general bajó al menos el umbral del webhook (10 % por defecto, 1–90 % por webhook). Puntuación anterior y nueva, la caída en puntos y en porcentaje, y el cambio de cada categoría.
  • visibility.lost: un asistente de IA mencionaba tu marca en su última respuesta a una pregunta seguida y ya no lo hace. Incluye el asistente, la pregunta y named_instead, los competidores que recomienda en su lugar.
  • visibility.gained: un asistente menciona ahora tu marca y antes no, con su posición.
  • scan.completed: terminó un escaneo (semanal, manual o una nueva comprobación). Puntuaciones, número de problemas y qué cambió.
  • answers.updated: nuevas respuestas de IA para una pregunta seguida, una entrada por asistente, con el mismo formato que /answers.
  • site.created y site.deleted.

Usa Enviar prueba en la página de Integraciones para recibir un evento ping.

Slack, Discord, Asana, ClickUp

Cada webhook tiene un formato de mensaje. Pega la dirección de un webhook entrante de Slack o Discord y OLAB Assist enviará una alerta legible de una línea con un enlace, en el idioma de la cuenta (las direcciones de Slack y Discord se detectan automáticamente). Para Asana, ClickUp, Trello, HubSpot y otros, usa el formato JSON con Zapier, Make o n8n: un disparador "Catch webhook" seguido de "Create task" convierte cada score.dropped o visibility.lost en una tarea. Cada envío lleva OLAB-Signature; Slack y Discord simplemente lo ignoran.

Verificar la firma

Cada solicitud lleva OLAB-Event, OLAB-Delivery y OLAB-Signature: t=<segundos unix>,v1=<hex>. La firma es un HMAC-SHA256 de t + "." + cuerpo sin procesar con el secreto de firma de tu webhook. Compárala en tiempo constante y rechaza marcas de tiempo antiguas:

// Node.js
import crypto from 'node:crypto';
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
# Python
import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Reintentos

Responde con cualquier estado 2xx en menos de 10 segundos. Cualquier otro resultado se reintenta tras unos 5 minutos, 30 minutos, 2 horas, 6 horas y 24 horas. Tras 25 envíos fallidos seguidos el webhook se pausa; reactívalo en la página de Integraciones. Usa id para ignorar un evento que ya procesaste.

Servidor MCP

El endpoint MCP es https://api.olabassist.com/mcp (Streamable HTTP). Expone los endpoints de la API como herramientas de solo lectura: list_sites, get_site, get_findings, get_ai_answers, get_score_history, get_trends, get_changes.

Clientes que aceptan cabeceras (Claude Code, Cursor y otros):

{
  "mcpServers": {
    "olab-assist": {
      "url": "https://api.olabassist.com/mcp",
      "headers": { "Authorization": "Bearer olab_YOUR_KEY" }
    }
  }
}

Claude Code: claude mcp add --transport http olab-assist https://api.olabassist.com/mcp --header "Authorization: Bearer olab_YOUR_KEY"

Los clientes que solo aceptan una URL pueden usar https://api.olabassist.com/mcp/olab_YOUR_KEY. Trata esa URL como una contraseña y usa una clave aparte para poder revocarla por separado.

Preguntas de ejemplo: “¿Qué sitios de mis clientes perdieron puntos esta semana?”, “¿A quién recomienda ChatGPT en lugar de example.com?”, “Enumera los problemas críticos de example.com con la solución de cada uno.”

Looker Studio (Data Studio)

El conector de OLAB Assist para Looker Studio lee la misma API v1. En la página de Integraciones crea una clave, elige Conectar en Looker Studio, permite el acceso y pega la clave. Los datos se leen al abrir el informe y se conservan durante el periodo de actualización de la fuente de datos (12 horas por defecto; elige 15 minutos o 1 hora para actualizaciones más rápidas). Google cambió el nombre de Looker Studio a Data Studio en 2026; es el mismo producto.

Elige una tabla por fuente de datos y filtra por un sitio o por todos. Combina fuentes de datos en un informe con el campo Sitio. Cada tabla se abre con un gráfico predeterminado útil.

  • Historial de puntuación (por defecto: puntuación GEO en el tiempo): una fila por escaneo con fecha del escaneo, sitio, informe y todas las puntuaciones y recuentos de problemas. Sigue el rango de fechas del informe.
  • Visibilidad en IA frente a competidores (por defecto: menciones por marca): una fila por marca seguida en cada respuesta de IA, con fecha de la pregunta, sitio, marca, marca propia, asistente, pregunta, intención y las métricas de menciones, citas y posición. Grafícalo en el tiempo por marca para compararte con los competidores.
  • Tendencia de problemas por categoría (por defecto: problemas críticos en el tiempo): una fila por escaneo y categoría (SEO, GEO, AEO, AIO) con problemas críticos, advertencias, problemas abiertos y la puntuación de la categoría.
  • Sitios: sitio, nombre de marca, última comprobación, informe, puntuación, puntuación SEO/GEO/AEO/AIO, problemas críticos, advertencias, respuestas de IA revisadas, respuestas que mencionan la marca, tasa de mención y posición entre las marcas seguidas.
  • Problemas abiertos: sitio, problema, estado, categoría, impacto, evidencia, cómo solucionarlo, dónde, id de comprobación y un recuento de problemas.
  • Respuestas de IA: una fila por respuesta con fecha de la pregunta, sitio, pregunta, intención, asistente, mencionada, citada como fuente, tono, marcas mencionadas y las métricas de respuestas, respuestas que mencionan la marca, respuestas que citan el sitio y posición cuando te mencionan. Sigue el rango de fechas del informe.

Un buen punto de partida: una serie temporal de Puntuación desde Historial de puntuación y una tabla de respuestas que mencionan la marca ÷ respuestas por asistente desde Respuestas de IA.

Notion

No necesitas código. En la página de Integraciones elige Conectar Notion. En la pantalla de aprobación de Notion, duplica la plantilla AI Visibility Dashboard (un clic, nada más que elegir) o comparte una página y selecciónala. Obtienes una página de panel con tu marca, un resumen por sitio y tres bases de datos integradas, que se actualizan tras cada escaneo y cada nueva respuesta de IA (como mucho una hora después, o al instante con Sincronizar ahora):

  • Sitios: una fila por sitio con la puntuación general y las de SEO, GEO, AEO y AIO, problemas críticos y advertencias, con qué frecuencia te mencionan las respuestas de IA, tu posición entre las marcas seguidas, fechas y enlaces al informe y al panel.
  • Problemas: hallazgos abiertos con estado, categoría, impacto, evidencia y cómo solucionarlos. Los problemas resueltos se marcan como Resuelto en lugar de borrarse.
  • Respuestas de IA (el registro semanal de preguntas de IA): una fila por respuesta desde los últimos 30 días, con la pregunta, su intención, el asistente, si te mencionaron, la posición, la cita, el tono, las marcas mencionadas y las fuentes.

Las filas se actualizan en su sitio y nunca se duplican. Puedes añadir tus propias columnas y vistas; nuestras columnas se sobrescriben en cada sincronización. Las columnas nuevas que añadamos aparecen automáticamente en tus bases de datos existentes. Al desconectar se detienen las actualizaciones y las páginas permanecen en Notion.

Intención y tono

Cada pregunta seguida recibe una etiqueta de intención: research (investigación), comparison (comparación), purchase (compra) o brand (marca), asignada una vez por un modelo de lenguaje pequeño (con palabras clave como respaldo). Cuando una respuesta menciona tu marca, su tono se etiqueta como positive (positivo), neutral (neutro) o negative (negativo). Ambos aparecen en la API (questions[].intent, answers[].question.intent, answers[].sentiment, ai_visibility.by_intent), en Notion y en Looker Studio, y el panel puede filtrar las respuestas por ellos.

Versiones

Esta es la versión 1. Dentro de v1 solo añadimos: nuevos endpoints, nuevos campos y nuevos tipos de evento. No eliminamos ni renombramos campos, ni cambiamos su significado o su tipo. Ignora los campos que no conozcas y tu integración seguirá funcionando a medida que añadimos funciones. Si alguna vez hace falta un cambio incompatible, se publicará como /api/v2 junto a v1, y v1 seguirá funcionando durante un periodo de transición anunciado por correo.

Historial de cambios

  • 2026-10: lanzamiento de v1: API REST, webhooks (scan.completed, answers.updated, site.created, site.deleted), el servidor MCP y la sincronización con Notion.
  • 2026-10: alertas (score.dropped, visibility.lost, visibility.gained), formatos de Slack y Discord, la plantilla de panel de Notion, tablas de competidores y categorías en Looker Studio, intención de las preguntas.