API pública v1

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

1. Inicia sesión en MencionAI.
2. Abre Configuración → Claves de API.
3. 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)
• Cliente TypeScript: guía del SDK
• Partners que incorporan visibilidad: guía de partners

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.