REST管理API · Aiqbee Hive

一套用于资源配置和自动化的小型REST API：创建Brain、列出Brain、修改设置、软删除Brain。交互式Swagger文档位于/api/v1/docs，是请求和响应结构的权威参考。

这不是面向智能体的接口。这里没有搜索端点，也没有神经元的增删改查。凡是AI应该做的事，请使用MCP。

首先开启两项设置

管理API默认关闭，且受两个相互独立的层级控制，必须同时开启，否则所有请求都会被拒绝：

Hive全局：由管理员在管理 → 配置中启用API。
按服务账号：必须在管理 → 服务账号中为该账号单独授予api_access_enabled。该选项默认关闭，因此为MCP创建的账号在您明确允许之前无法调用REST。

与MCP使用的服务账号Bearer令牌相同，参见获取访问令牌。以Authorization: Bearer <token>形式传递。

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

方法&路径	用途
`POST /api/v1/brains`	创建Brain。调用方服务账号将成为其所有者。可选择基于模板预置神经元类型。
`GET /api/v1/brains`	列出调用方可见的Brain，不包括已软删除的Brain。
`GET /api/v1/brains/{brainId}`	获取单个Brain。
`PATCH /api/v1/brains/{brainId}`	更新白名单内的设置。白名单以外的字段将被忽略，不会报错。
`DELETE /api/v1/brains/{brainId}`	软删除。该Brain将不再出现在读取结果中，但神经元会保留。
`GET /api/v1/brain-templates`	可用于为新Brain预置神经元类型的模板。

请求体使用camelCase：auditEnabled、brainTemplateId、advancedSecurityEnabled。
PATCH采用白名单机制。只有可识别的字段才会生效；发送ownerUserId会被静默忽略，而不会让您借此重新分配所有权。
错误以RFC 7807问题文档形式返回，包含title和detail。
许可证限制在此同样适用。超出共享额度创建Brain会因许可证错误而失败，API并不能绕过这些上限。
付费功能在此同样无法启用。在免费版Hive上设置auditEnabled或advancedSecurityEnabled会被拒绝，与在界面和MCP中的行为完全一致。