REST-Management-API · Aiqbee Hive

/api/v1 für Bereitstellung und Automatisierung – und wann Sie es nicht verwenden sollten.

Eine kleine REST-API für Bereitstellung und Automatisierung – Brains erstellen, auflisten, Einstellungen patchen, per Soft-Delete löschen. Interaktive Swagger-Dokumentation wird unter /api/v1/docs bereitgestellt und ist die maßgebliche Referenz für Anfrage- und Antwortformate.

Dies ist nicht die Agentenschnittstelle. Es gibt hier keinen Such-Endpunkt und kein Neuron-CRUD. Für alles, was eine KI tun soll, verwenden Sie MCP.

Zwei Dinge, die Sie zuerst einschalten sollten

Die Management-API ist standardmäßig geschlossen, und zwar auf zwei unabhängigen Ebenen – beide müssen geöffnet sein, sonst wird jede Anfrage abgelehnt:

Hive-weit: Ein Administrator aktiviert die API unter Admin → Konfiguration.
Pro Dienstkonto: api_access_enabled muss diesem bestimmten Konto unter Admin → Dienstkonten erteilt werden. Standardmäßig ist es aus, sodass ein für MCP erstelltes Konto REST nicht aufrufen kann, bis Sie dies bewusst erlauben.

Authentifizierung

Dasselbe Bearer-Token eines Dienstkontos wie für MCP – siehe Zugriffstoken erhalten. Übergeben Sie es als Authorization: Bearer <token>.

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

Endpunkte

Methode & Pfad	Zweck
`POST /api/v1/brains`	Ein Brain erstellen. Das aufrufende Dienstkonto wird dessen Eigentümer. Optional Neuronentypen aus einer Vorlage übernehmen.
`GET /api/v1/brains`	Brains auflisten, die der Aufrufer sehen kann. Per Soft-Delete gelöschte Brains sind ausgeschlossen.
`GET /api/v1/brains/{brainId}`	Ein Brain abrufen.
`PATCH /api/v1/brains/{brainId}`	Zulässige Einstellungen aktualisieren. Felder außerhalb der Zulassungsliste werden ignoriert, statt einen Fehler auszulösen.
`DELETE /api/v1/brains/{brainId}`	Weiches Löschen. Das Brain erscheint nicht mehr in Lesevorgängen; Neuronen bleiben erhalten.
`GET /api/v1/brain-templates`	Vorlagen zum Befüllen der Neuronentypen eines neuen Brains.

Konventionen

Bodys sind camelCase – auditEnabled, brainTemplateId, advancedSecurityEnabled.
PATCH ist eine Whitelist. Nur erkannte Felder werden angewendet; das Senden von ownerUserId bewirkt stillschweigend nichts, statt Ihnen zu erlauben, den Eigentümer zu ändern.
Fehler sind RFC-7807-Problemdokumente mit title und detail.
Auch hier gelten die Lizenzgrenzen. Das Erstellen eines Brains über das gemeinsame Kontingent hinaus schlägt mit einem Lizenzfehler fehl – die API ist kein Weg, die Obergrenzen zu umgehen.
Kostenpflichtige Funktionen können auch hier nicht aktiviert werden. Das Setzen von auditEnabled oder advancedSecurityEnabled auf einem Hive im kostenlosen Tarif wird abgelehnt, genau wie in der Oberfläche und über MCP.

Welche Oberfläche für welche Aufgabe

Aufgabe	Verwenden
Agent sucht oder erfasst Wissen	MCP
Brains für ein neues Team oder einen neuen Mandanten einrichten	REST
Vorhandene Dokumente per Massenimport übernehmen	MCP-Schreib-Tools, direkt aufgerufen
Ein ganzes Brain zwischen Hives oder in andere Tools verschieben	OKF-Export/-Import in der Admin-Oberfläche — siehe OKF-Export & -Import
Einstellungen für viele Brains gleichzeitig aktivieren	REST
Benutzerzugriff verwalten	Die Weboberfläche oder MCP-Zugriffs-Tools