Primeros pasos con la API

Usa la API de MencionAI para leer datos de visibilidad de marca y lanzar scans desde tus apps, dashboards o automatizaciones.

Antes de empezar

Necesitas una cuenta MencionAI con al menos un workspace (marca/dominio) configurado.

Paso 1 — Crear una clave de API

Inicia sesión en MencionAI.
Abre Configuración → Claves de API.
Haz clic en Crear clave de API y copia el valor de inmediato. Solo se muestra una vez.

Las claves tienen el formato mak_live_… (producción) o mak_test_… (sandbox).

Guarda la clave en un gestor de secretos o variable de entorno — nunca la subas a git ni la expongas en código del navegador.

Paso 2 — Hacer tu primera solicitud

curl -s \
  -H "Authorization: Bearer TU_CLAVE_API" \
  https://www.mencionai.com/api/v1/organization

Ejemplo de respuesta:

{
  "id": 1,
  "name": "Acme Inc",
  "plan": "Growth",
  "subscription_status": "active"
}

Paso 3 — Listar workspaces y leer visibilidad

# Listar workspaces
curl -s \
  -H "Authorization: Bearer TU_CLAVE_API" \
  https://www.mencionai.com/api/v1/workspaces

# Resumen de visibilidad del workspace 42
curl -s \
  -H "Authorization: Bearer TU_CLAVE_API" \
  https://www.mencionai.com/api/v1/workspaces/42/visibility/summary

Qué puedes construir

| Objetivo | Empieza aquí | |----------|--------------| | Dashboard interno de BI | GET /workspaces/:id/visibility/summary | | Alerta cuando termine un scan | Webhooks + visibility.scan.completed | | Gráfico embebido en tu producto | Tokens de embed → iframe | | Re-scans automatizados | POST /workspaces/:id/scans + polling en GET /jobs/:id |

Próximos pasos

Referencia completa en la página de la API (incluye explorador OpenAPI interactivo)
Servidor MCP para Cursor / Claude Desktop: guía MCP
Cliente TypeScript: guía del SDK
Partners que incorporan visibilidad: guía de partners

MencionAI MCP

Usa el servidor MCP de MencionAI para leer visibilidad en búsquedas de IA y encolar scans desde Cursor, Claude Desktop o cualquier cliente MCP.

El MCP es un adaptador fino sobre la API pública v2. Usa tu clave API y los mismos scopes que el HTTP. Las tools no hablan con la base de datos directamente.

Antes de empezar

Crea una clave en Ajustes → Claves API (mak_live_… o mak_test_…). La pantalla también tiene snippets de instalación MCP.
Instala Node.js 20+ (para stdio local).
Concede los scopes que necesites:
- organization:read + workspaces:read — listar workspaces y leer visibilidad
- jobs:read + scopes de escritura/scan — encolar / esperar scans
- visibility:answers:read — solo si necesitas get_visibility_responses (extractos de respuesta)

Nunca pases la clave API como argumento de tool. Ponla en el entorno del proceso MCP (stdio) o como Authorization: Bearer (alojado).

Stdio local (bueno para empezar)

pnpm add -g @mencionai/mcp
# o: npx -y @mencionai/mcp

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "mencionai": {
      "command": "npx",
      "args": ["-y", "@mencionai/mcp"],
      "env": {
        "MENCIONAI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mencionai": {
      "command": "npx",
      "args": ["-y", "@mencionai/mcp"],
      "env": {
        "MENCIONAI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Opcional: define MENCIONAI_API_BASE_URL para un base URL v2 no productivo.

MCP alojado (preferido para agentes en producción)

Usa el endpoint Streamable HTTP alojado cuando quieras rate limits y telemetría de producto. Stdio en máquinas de clientes no escribe eventos de uso.

URL: https://mcp.mencionai.com/mcp

Ejemplo de config remota (sustituye la clave; la forma JSON exacta depende del cliente MCP):

{
  "mcpServers": {
    "mencionai": {
      "url": "https://mcp.mencionai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Autentica con Authorization: Bearer YOUR_API_KEY. Nunca pases la clave como argumento de tool.

Flujo preferido

Usa este camino salvo que el usuario pida un recorte crudo:

list_workspaces
get_visibility_overview
explain_visibility_gaps / compare_competitors
wait_for_visibility_scan cuando haga falta refrescar (consume cuota del plan)
get_visibility_series para tendencias

No llames tools finas de visibilidad (get_visibility_summary, get_visibility_mentions, get_visibility_competitors, get_visibility_coverage, get_visibility_citations) salvo que la salida compuesta sea insuficiente o el usuario pida ese recorte. get_visibility_responses requiere visibility:answers:read y falla cerrado sin él.

Tools

| Tool | Propósito | |------|-----------| | get_visibility_overview | Empieza aquí — snapshot compuesto (summary + coverage + competitors + citations) | | compare_competitors | Rankea rivales por mentions/citations vs la marca | | explain_visibility_gaps | Prompts donde aparecen competidores y no la marca | | wait_for_visibility_scan | Encola + espera el scan (por defecto 60s, máx. 120s; consume cuota) | | get_visibility_series | Scores diarios (7d | 30d | 90d) | | get_organization / list_workspaces / get_workspace | Lecturas de org y workspace | | get_visibility_responses | Extractos de respuesta (requiere visibility:answers:read) | | get_visibility_coverage / citations / summary / mentions / competitors | Lecturas finas (power user) | | enqueue_visibility_scan / get_job | Scan manual + poll (prefiere wait_for_visibility_scan) |

Ejemplos de prompts

Share of voice: “Con MencionAI, abre mi workspace y resume dónde perdemos share frente a los tres principales competidores en ChatGPT.”
Gaps: “¿Qué prompts monitorizados mencionan a un competidor pero no a nuestra marca? Lista los hosts rivales.”
Citas: “Desde el overview de visibilidad, ¿qué dominios nos citan más y qué URLs top no son de nuestro sitio?”
Rescan: “Encola un scan de mi workspace principal, espera hasta 60 segundos y refresca el overview.”
Tendencias: “Muestra la serie de 30 días de mi workspace principal y destaca el último cambio de score.”

Solución de problemas

| Síntoma | Qué revisar | |---------|-------------| | 401 / no autorizado | Clave ausente, revocada o entorno incorrecto (mak_live_ vs mak_test_) | | Error de scope / forbidden | Falta workspaces:read (o scopes de escritura de scan) | | get_visibility_responses falla cerrado | Añade visibility:answers:read al crear la clave | | Scan lento o rechazado | Cuota del plan; prefiere wait_for_visibility_scan con timeout ≤ 120s | | El agente pide la clave API | MCP mal configurado — la clave va en env / Bearer, nunca en argumentos |

Siguientes pasos

Referencia de la API

La API REST de MencionAI te permite acceder a datos de organización y workspace, métricas de visibilidad, scans, webhooks y tokens de embed.

URL base: https://www.mencionai.com/api/v1

Especificación OpenAPI: Descargar YAML

Todas las solicitudes requieren autenticación salvo que se indique lo contrario.

Autenticación

Envía tu clave de API en el encabezado Authorization:

Authorization: Bearer mak_live_xxxxxxxx

| Prefijo de clave | Uso | |------------------|-----| | mak_live_ | Datos de producción | | mak_test_ | Pruebas y desarrollo |

Crea claves en el panel de MencionAI en Configuración → Claves de API.

Alcances

Al crear una clave, se le asigna un conjunto de alcances. Cada endpoint requiere un alcance específico:

| Alcance | Permite | |---------|---------| | organization:read | Leer información de la organización | | workspaces:read | Listar workspaces y datos de visibilidad | | workspaces:write | Encolar scans de visibilidad | | jobs:read | Consultar estado de jobs de scan | | embed:create | Crear tokens de embed de corta duración | | webhooks:manage | Registrar y gestionar endpoints de webhook |

Si falta un alcance, la API devuelve 403 con código MISSING_SCOPE.

Límites de tasa

Los límites se aplican por organización y dependen de tu plan:

| Plan | Solicitudes por minuto | |------|------------------------| | Free | 30 | | Starter | 60 | | Growth | 300 | | Enterprise | 1.000 |

Cada respuesta incluye:

X-RateLimit-Limit — límite de tu plan
X-RateLimit-Remaining — solicitudes restantes en la ventana actual

Al superar el límite, la API devuelve 429 con encabezado Retry-After (segundos hasta poder reintentar).

Errores

Los errores usan un formato JSON consistente:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or revoked API key",
    "request_id": "req_abc123"
  }
}

Códigos comunes:

| Código | HTTP | Significado | |--------|------|-------------| | UNAUTHORIZED | 401 | Clave de API ausente o inválida | | FORBIDDEN | 403 | Alcance ausente o función no incluida en tu plan | | NOT_FOUND | 404 | Workspace o recurso no encontrado | | RATE_LIMIT_EXCEEDED | 429 | Demasiadas solicitudes | | IDEMPOTENCY_KEY_REQUIRED | 422 | POST de scan sin Idempotency-Key | | VALIDATION_ERROR | 422 | Cuerpo o parámetro de path inválido |

Incluye el request_id al contactar soporte.

Organización

`GET /organization`

Devuelve el nombre, plan y estado de suscripción de tu organización.

curl -H "Authorization: Bearer TU_CLAVE_API" \
  https://www.mencionai.com/api/v1/organization

Workspaces

Un workspace representa una marca/dominio que sigues en MencionAI.

`GET /workspaces`

Lista todos los workspaces de tu organización.

{
  "workspaces": [
    {
      "id": 42,
      "domain": "acme.com",
      "brand_name": "Acme",
      "created_at": "2026-01-15T10:00:00.000Z"
    }
  ]
}

`GET /workspaces/:id`

Devuelve metadatos de un workspace.

Visibilidad

Todos los endpoints de visibilidad requieren workspaces:read.

`GET /workspaces/:id/visibility/summary`

Métricas generales: menciones, citas, prompts monitorizados, proveedores, última sincronización.

`GET /workspaces/:id/visibility/mentions`

Menciones agrupadas por prompt/palabra clave.

`GET /workspaces/:id/visibility/competitors`

Estadísticas de visibilidad de competidores (menciones y citas por host).

Scans

Dispara un nuevo scan de visibilidad en IA para un workspace.

`POST /workspaces/:id/scans`

Requiere workspaces:write y el encabezado Idempotency-Key (único por solicitud lógica). Reutilizar la misma clave con el mismo cuerpo devuelve la respuesta original en lugar de encolar de nuevo.

curl -X POST \
  -H "Authorization: Bearer TU_CLAVE_API" \
  -H "Idempotency-Key: scan-2026-07-06-acme-001" \
  https://www.mencionai.com/api/v1/workspaces/42/scans

Respuesta (202):

{
  "job_id": 901,
  "status": "pending"
}

`GET /jobs/:id`

Consulta el estado del job. Requiere jobs:read.

{
  "id": 901,
  "type": "ai_scan",
  "status": "completed",
  "created_at": "2026-07-06T12:00:00.000Z"
}

Valores de estado: pending, processing, completed, failed.

Flujo típico: encolar scan → consultar cada pocos segundos hasta completed → obtener resumen de visibilidad actualizado.

Webhooks

Recibe callbacks HTTP cuando ocurran eventos en tu organización. Disponible en planes Starter y superiores.

Registrar un endpoint

curl -X POST \
  -H "Authorization: Bearer TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-app.com/webhooks/mencionai",
    "events": ["visibility.scan.completed"]
  }' \
  https://www.mencionai.com/api/v1/webhooks

La respuesta incluye un secret — guárdalo de inmediato. Lo necesitas para verificar firmas.

Tipos de evento

| Evento | Cuándo se dispara | |--------|-------------------| | visibility.scan.enqueued | Se aceptó un scan | | visibility.scan.completed | Un scan terminó correctamente | | report.generated | Un informe está listo |

Formato del payload

{
  "id": "evt_uuid",
  "type": "visibility.scan.completed",
  "created_at": "2026-07-06T12:05:00.000Z",
  "data": {
    "workspace_id": 42,
    "job_id": 901,
    "result_id": 555
  }
}

Verificar firmas

Cada entrega incluye:

X-MencionAI-Signature: t=1710000000,v1=abc123...

Verifica calculando HMAC-SHA256 sobre {timestamp}.{cuerpo_crudo} con el secret del endpoint y compara con v1.

Gestionar endpoints

| Método | Path | Acción | |--------|------|--------| | GET | /webhooks | Listar endpoints | | GET | /webhooks/:id | Obtener un endpoint | | PATCH | /webhooks/:id | Actualizar URL o eventos | | DELETE | /webhooks/:id | Desactivar endpoint |

Tokens de embed

Muestra la visibilidad de MencionAI dentro de tu producto mediante un iframe seguro.

`POST /embed-tokens`

Requiere embed:create.

curl -X POST \
  -H "Authorization: Bearer TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{ "workspace_id": 42, "ttl_sec": 3600 }' \
  https://www.mencionai.com/api/v1/embed-tokens

{
  "token": "met_...",
  "expires_in": 3600,
  "workspace_id": 42
}

Carga en un iframe:

https://www.mencionai.com/embed/v1/workspaces/42/summary?token=met_...

Los tokens son de corta duración. Crea uno nuevo en el servidor cuando expire el anterior — no expongas tu clave de API en el navegador.

Consulta la guía de partners para buenas prácticas de incorporación.

API pública v1

Primeros pasos con la API

Antes de empezar

Paso 1 — Crear una clave de API

Paso 2 — Hacer tu primera solicitud

Paso 3 — Listar workspaces y leer visibilidad

Qué puedes construir

Próximos pasos

MencionAI MCP

Antes de empezar

Stdio local (bueno para empezar)

MCP alojado (preferido para agentes en producción)

Flujo preferido

Tools

Ejemplos de prompts

Solución de problemas

Siguientes pasos

Referencia de la API

Autenticación

Alcances

Límites de tasa

Errores

Organización

GET /organization

Workspaces

GET /workspaces

GET /workspaces/:id

Visibilidad

GET /workspaces/:id/visibility/summary

GET /workspaces/:id/visibility/mentions

GET /workspaces/:id/visibility/competitors

Scans

POST /workspaces/:id/scans

GET /jobs/:id

Webhooks

Registrar un endpoint

Tipos de evento

Formato del payload

Verificar firmas

Gestionar endpoints

Tokens de embed

POST /embed-tokens

`GET /organization`

`GET /workspaces`

`GET /workspaces/:id`

`GET /workspaces/:id/visibility/summary`

`GET /workspaces/:id/visibility/mentions`

`GET /workspaces/:id/visibility/competitors`

`POST /workspaces/:id/scans`

`GET /jobs/:id`

`POST /embed-tokens`