REST management API

/api/v1 for provisioning and automation — and when not to use it.

A small REST API for provisioning and automation — creating brains, listing them, patching settings, soft-deleting them. Interactive Swagger documentation is served at /api/v1/docs and is the authoritative reference for request and response shapes.

This is not the agent interface. There is no search endpoint and no neuron CRUD here. For anything an AI should be doing, use MCP.

Two things to switch on first

The management API is closed by default, at two independent levels — both must be open or every request is refused:

Hive-wide: an administrator enables the API in Admin → Configuration.
Per service account: api_access_enabled must be granted to that specific account, from Admin → Service Accounts. It defaults to off, so an account created for MCP cannot call REST until you deliberately allow it.

Authentication

The same service-account bearer token used for MCP — see getting an access token. Pass it as Authorization: Bearer <token>.

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

Endpoints

Method & path	Purpose
`POST /api/v1/brains`	Create a brain. The calling service account becomes its owner. Optionally seed neuron types from a template.
`GET /api/v1/brains`	List brains the caller can see. Soft-deleted brains are excluded.
`GET /api/v1/brains/{brainId}`	Fetch one brain.
`PATCH /api/v1/brains/{brainId}`	Update whitelisted settings. Fields outside the whitelist are ignored rather than erroring.
`DELETE /api/v1/brains/{brainId}`	Soft-delete. The brain stops appearing in reads; neurons are retained.
`GET /api/v1/brain-templates`	Templates available for seeding a new brain's neuron types.

Conventions

Bodies are camelCase — auditEnabled, brainTemplateId, advancedSecurityEnabled.
PATCH is a whitelist. Only recognised fields apply; sending ownerUserId silently does nothing rather than letting you reassign ownership.
Errors are RFC 7807 problem documents with a title and detail.
Licence limits apply here too. Creating a brain past the pooled allowance fails with a licence error — the API is not a way around the caps.
Paid features cannot be enabled here either. Setting auditEnabled or advancedSecurityEnabled on a free-tier Hive is refused, exactly as in the UI and over MCP.

Which interface for which job

Task	Use
Agent searching or recording knowledge	MCP
Standing up brains for a new team or tenant	REST
Bulk-importing existing documents	MCP write tools, called directly
Turning settings on across many brains	REST
Managing user access	The web UI, or MCP access tools