API REST de gestion · Aiqbee Hive

/api/v1 pour le provisionnement et l’automatisation — et quand ne pas l’utiliser.

Une petite API REST pour le provisionnement et l’automatisation — création de brains, listage, modification de paramètres, suppression logique. La documentation Swagger interactive est servie à /api/v1/docs et fait foi pour la forme des requêtes et des réponses.

Ce n’est pas l’interface des agents. Il n’y a ici ni point de terminaison de recherche ni CRUD de neurones. Pour tout ce qu’une IA doit faire, utilisez MCP.

Deux choses à activer d'abord

L'API de gestion est fermée par défaut, à deux niveaux indépendants — les deux doivent être ouverts, sinon toute requête est refusée :

À l’échelle du Hive : un administrateur active l’API dans Admin → Configuration.
Par compte de service : api_access_enabled doit être accordé à ce compte précis, depuis Admin → Comptes de service. Il est désactivé par défaut, de sorte qu’un compte créé pour MCP ne peut pas appeler REST tant que vous ne l’autorisez pas délibérément.

Authentification

Le même jeton porteur de compte de service que pour MCP — voir obtenir un jeton d'accès. Transmettez-le sous la forme Authorization: Bearer <token>.

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

Points de terminaison

Méthode & chemin	Objet
`POST /api/v1/brains`	Crée un brain. Le compte de service appelant en devient le propriétaire. Possibilité d’initialiser les types de neurones à partir d’un modèle.
`GET /api/v1/brains`	Liste les brains que l’appelant peut voir. Les brains supprimés logiquement sont exclus.
`GET /api/v1/brains/{brainId}`	Récupère un brain.
`PATCH /api/v1/brains/{brainId}`	Mettre à jour les paramètres autorisés. Les champs hors liste autorisée sont ignorés plutôt que de provoquer une erreur.
`DELETE /api/v1/brains/{brainId}`	Suppression logique. Le Brain n'apparaît plus en lecture ; les neurones sont conservés.
`GET /api/v1/brain-templates`	Modèles disponibles pour initialiser les types de neurone d'un nouveau Brain.

Conventions

Les corps de requête sont en camelCase — auditEnabled, brainTemplateId, advancedSecurityEnabled.
PATCH fonctionne par liste blanche. Seuls les champs reconnus sont appliqués ; envoyer ownerUserId ne fait silencieusement rien, au lieu de vous laisser réattribuer la propriété.
Les erreurs sont des documents de problème RFC 7807 avec un title et un detail.
Les limites de licence s’appliquent aussi ici. Créer un brain au-delà du quota mutualisé échoue avec une erreur de licence — l’API ne permet pas de contourner les plafonds.
Les fonctionnalités payantes ne peuvent pas non plus être activées ici. Définir auditEnabled ou advancedSecurityEnabled sur un Hive de l’offre gratuite est refusé, exactement comme dans l’interface et via MCP.

Quelle interface pour quelle tâche

Tâche	Utiliser
Agent qui recherche ou enregistre des connaissances	MCP
Mettre en place des Brains pour une nouvelle équipe ou un nouveau locataire	REST
Import en masse de documents existants	Outils d'écriture MCP, appelés directement
Déplacer un Brain entier entre des Hives, ou vers d'autres outils	Export/import OKF dans l'interface d'administration — voir Export & import OKF
Activer des paramètres sur de nombreux Brains	REST
Gestion des accès utilisateurs	L'interface web, ou les outils d'accès MCP