API de administración REST

Una pequeña API REST para aprovisionamiento y automatización: crear Brains, listarlos, modificar ajustes y eliminarlos de forma lógica. La documentación interactiva de Swagger se sirve en /api/v1/docs y es la referencia autorizada de las formas de solicitud y respuesta.

Esta no es la interfaz para agentes. Aquí no hay endpoint de búsqueda ni CRUD de neuronas. Para todo lo que deba hacer una IA, use MCP.

Dos cosas que activar primero

La API de administración está cerrada de forma predeterminada, en dos niveles independientes: ambos deben estar abiertos o se rechaza toda solicitud:

En todo el Hive: un administrador habilita la API en Admin → Configuración.
Por cuenta de servicio: api_access_enabled debe concederse a esa cuenta concreta, desde Admin → Cuentas de servicio. Por defecto está desactivado, de modo que una cuenta creada para MCP no puede llamar a REST hasta que usted lo permita deliberadamente.

Autenticación

El mismo token bearer de cuenta de servicio utilizado para MCP; consulte cómo obtener un token de acceso. Páselo como Authorization: Bearer <token>.

curl https://hive.example.com/api/v1/brains \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoints

Método & ruta	Finalidad
`POST /api/v1/brains`	Crear un Brain. La cuenta de servicio que llama se convierte en su propietaria. Opcionalmente, inicializa los tipos de neurona a partir de una plantilla.
`GET /api/v1/brains`	Lista los Brains que puede ver quien llama. Se excluyen los Brains eliminados de forma lógica.
`GET /api/v1/brains/{brainId}`	Obtener un Brain.
`PATCH /api/v1/brains/{brainId}`	Actualizar ajustes de la lista permitida. Los campos fuera de la lista permitida se ignoran en lugar de generar un error.
`DELETE /api/v1/brains/{brainId}`	Eliminación lógica. El Brain deja de aparecer en las lecturas; las neuronas se conservan.
`GET /api/v1/brain-templates`	Plantillas disponibles para sembrar los tipos de neurona de un nuevo Brain.

Convenciones

Los cuerpos usan camelCase — auditEnabled, brainTemplateId, advancedSecurityEnabled.
PATCH es una lista blanca. Solo se aplican los campos reconocidos; enviar ownerUserId no hace nada en silencio en lugar de permitir reasignar la propiedad.
Los errores son documentos de problema RFC 7807 con un title y un detail.
Los límites de la licencia también se aplican aquí. Crear un Brain por encima de la asignación agrupada falla con un error de licencia: la API no es una forma de eludir los límites.
Las funciones de pago tampoco se pueden habilitar aquí. Establecer auditEnabled o advancedSecurityEnabled en un Hive de plan gratuito se rechaza, exactamente igual que en la interfaz y mediante MCP.

Qué interfaz para cada tarea

Tarea	Usar
Agente que busca o registra conocimiento	MCP
Puesta en marcha de Brains para un nuevo equipo o inquilino	REST
Importación masiva de documentos existentes	Herramientas de escritura MCP, invocadas directamente
Mover un Brain completo entre Hives o a otras herramientas	Exportación/importación OKF en la interfaz de administración — consulte Exportación & importación OKF
Activar ajustes en muchos Brains a la vez	REST
Gestión del acceso de usuarios	La interfaz web o las herramientas de acceso MCP