La API, de la primera clave al primer informe.
Todo lo que el producto sirve programáticamente — informes, exports CSV, el feed de BI y el servidor MCP — detrás de una clave con alcance de proyecto.
La superficie pública es deliberadamente menor que el producto: es el contrato de serving — reporting, exports, el feed de BI y MCP — y nada más. Tu clave lee; nunca escribe. La única superficie de escritura es el conjunto de tools del servidor MCP, detrás de su propia plan flag.
Todo se sirve en el mismo origen que la app, servidor a servidor. No hay CORS: la API es para tu backend, tu notebook o tu cliente MCP, no para un navegador en otro origen.
URL base
Todo path REST de abajo cuelga de la base versionada:
https://app.bementioned.ai/api/v1Cada path tiene alcance de un proyecto. El servidor MCP vive junto a la base REST — su dirección está en su propio capítulo.
API keys
La clave se acuña por proyecto, en la app: Settings → API keys. El texto en claro aparece exactamente una vez, al crearla, y solo se guarda el hash — cópiala en ese momento. Las claves son revocables individualmente.
Una clave tiene el alcance de su proyecto y no puede excederlo: presentada contra otro proyecto responde 404, como si ese proyecto no existiera. Las claves son principals de solo lectura — toda escritura REST responde 403.
Autenticación
Envía la clave en cada petición, en cualquiera de los dos headers:
curl https://app.bementioned.ai/api/v1/projects/{project_id}/overview \
-H "X-API-Key: bm_your_key_here"Un header Authorization: Bearer con el mismo valor bm_ se acepta de forma equivalente — lo que empieza por bm_ se trata como clave; lo demás, como token de sesión.
Límites de peticiones
El tráfico autenticado por clave se limita a 200 peticiones por minuto por proyecto — un token bucket, así que ráfagas cortas de hasta 200 pasan. Por encima, la API responde 429 con un header Retry-After en segundos. Las peticiones rechazadas nunca debitan del bucket.
Errores
Los errores son JSON con un campo detail — una cadena, un objeto con código, o una lista de validación.
| Status | Significado |
|---|---|
401 | Credencial ausente, desconocida o revocada. |
403 | Una escritura con clave de solo lectura, o un plan sin la flag de la función. |
404 | Nada en esa dirección — incluida una clave válida presentada contra un proyecto ajeno. |
422 | El body falló la validación; el detail lista cada campo ofensor. |
429 | Límite de peticiones excedido; reintenta tras Retry-After segundos. |
Cuando un plan carece de la flag de una superficie, la API responde 403 y nombra la flag, para que el rechazo sea diagnosticable. Las flags:
{ "detail": { "code": "plan_flag_missing", "flag": "reporting_api" } }reporting_api · mcp · mcp_write · bi_connector · csv_export · actions · shopping · agent_analytics · deliverables
Capítulos
- Reporting API — las familias de informes, el contrato de filtros, export CSV.
- Servidor MCP — conectar un cliente, el roster de tools, escrituras.
- BI & webhook — el feed de BI y el webhook de ingest de logs.