API de Community Monitor

El Community Monitor crawlea plataformas públicas (Reddit, Hacker News, Twitter/X, Quora, Trustpilot, comentarios de YouTube, etc.) buscando mentions de tu marca o de keywords definidas. La API entrega las mentions raw más alerts agregados — ideal para conectar dashboards de reputación o bots de Slack a Rankion.

Contexto del módulo: Community Monitor.

Mentions

Una mention es un hallazgo individual: plataforma, autor, extracto de texto, sentiment, permalink.

Filtros (query params):

• ?platform=reddit|hackernews|twitter|trustpilot|quora|youtube
• ?sentiment=positive|neutral|negative
• ?keyword=<string> (text match sobre el body de la mention)
• ?from=YYYY-MM-DD&to=YYYY-MM-DD
• ?page=1&per_page=25

curl "$BASE/community/mentions?platform=reddit&sentiment=negative&from=2026-04-01" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[] | {id, platform, sentiment, url, snippet}'

Response (recortada):

{
  "data": [
    {
      "id": 451,
      "platform": "reddit",
      "author": "u/foo",
      "snippet": "I tried Rankion and the GEO scoring was…",
      "sentiment": "negative",
      "score": -0.42,
      "url": "https://reddit.com/r/seo/comments/…",
      "discovered_at": "2026-04-28T14:21:00Z"
    }
  ],
  "meta": {"current_page": 1, "per_page": 25, "total": 138}
}

Dispatchar scan

Un scan dispara un crawl run inmediato para una keyword concreta sobre las plataformas seleccionadas — independiente del schedule automático.

curl -X POST "$BASE/community/scan" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "keyword": "rankion ai",
    "platforms": ["reddit", "hackernews", "trustpilot"]
  }'

Respuesta 202 Accepted:

{
  "scan_id": 77,
  "status": "queued",
  "message": "Community scan dispatched"
}

El scan corre en background. Las mentions nuevas aparecen en la lista en cuanto el job termina (típicamente 30–120 s según número de plataformas).

Alerts

Los alerts son señales agregadas: acumulaciones de mentions negativas, caídas de sentiment, desplomes de review score. El sistema las consolida diaria/semanalmente.

curl "$BASE/community/alerts" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {id, type, severity, message, triggered_at, mentions_count}'

Valores típicos de type:

• sentiment_drop — el sentiment promedio está > 1 SD por debajo de la baseline
• negative_burst — un número llamativo de mentions negativas en una ventana corta
• review_alert — review sources externas reportan un desplome del score (ver API de Review Sources)

Notas

• Las mentions se deduplican por (platform, external_id) — el mismo comentario de Reddit nunca se guarda dos veces, aunque corran varios scans.
• El sentiment es heurístico (basado en modelo). Para fines legales/de compliance, comprueba siempre la URL original, no la etiqueta del score.
• Los auto-crawls corren en background (varias veces al día) — el POST /scan manual es solo para pulls ad hoc. Sin llamar a scan, la lista de mentions se llena igualmente.
• La disponibilidad por plataforma cambia. El crawl Twitter/X depende del estado de su API — si cae, un POST /scan con platforms:["twitter"] devuelve 503 o resultado vacío.
• El patrón de webhooks públicos para mentions (todavía) no está expuesto — si necesitas push en tiempo real, haz polling a /community/alerts cada minuto.

Relacionado: API de Review Sources · Community Monitor.