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

Las guías de conexión para Cursor, Claude, Codex, Antigravity y n8n están en el hub MCP.

URLs cortas para agentes (redirigen a este sitio): docs.mencionai.com/mcp.

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