Cloud API
The KB-1 Cloud API is the authenticated control plane for the Cloud web app, organization membership, vault entry, relay setup, Hosted diagnostics, and Cloud MCP integration approval. It is not a general note CRUD API. Agents should normally use the MCP surface described in MCP tools.
What this API is for
Section titled “What this API is for”Use the Cloud API to answer control-plane questions:
- Who is signed in?
- Which organizations does the account belong to?
- Which daemon mode does an organization use?
- Which vaults can this account enter?
- Is a Hosted daemon awake and healthy?
- Which signed entry assertion should the app use for a vault route?
Do not use the Cloud API as a general note CRUD API. Vault content operations belong to the vault engine: local daemon for local-only and self-hosted, Hosted daemon for Hosted.
Authentication
Section titled “Authentication”Most routes require the KB-1 Cloud session cookie created by sign-in. The API uses JSON responses and returns structured failure objects for invalid requests, missing sessions, access denials, and not-found resources.
GET /api/health is public and returns the Cloud API service name and
environment. Auth routes live under the Better Auth handler mounted by the API.
Settings and organizations
Section titled “Settings and organizations”| Route | Purpose | Notes |
|---|---|---|
GET /api/settings |
Return the signed-in profile and orgs. | Each org includes the user’s role, members, and daemon mode when present. |
PATCH /api/settings/profile |
Update profile name and image URL. | Requires a signed-in user. |
POST /api/auth/organization/update |
Rename an organization. | Better Auth organization route; requires admin access. |
POST /api/auth/organization/invite-member |
Invite a member by email. | Admin route; creates an invitation that can be accepted later. |
POST /api/auth/organization/accept-invitation |
Accept an invitation. | Used by the Cloud app invitation page. |
POST /api/auth/organization/remove-member |
Remove a member. | Admin route. |
POST /api/auth/organization/update-member-role |
Change admin/member role. |
Admin route. |
PATCH /api/orgs/:orgId/auto-admit |
Enable or disable Google Workspace auto-admit. | Admin route; binds the caller’s own Workspace domain and returns 409 on domain conflict. |
GET /api/orgs/:orgId/daemon/status |
Read self-hosted daemon control status. | Member route; only for self-hosted orgs. |
GET /api/orgs/:orgId/api-key |
Read the masked self-hosting daemon key. | Admin route; plaintext is never returned from this read. |
POST /api/orgs/:orgId/api-key |
Issue the self-hosting daemon key. | Admin route; plaintext returned once. |
POST /api/orgs/:orgId/api-key/rotate |
Rotate the self-hosting daemon key. | Admin route; plaintext returned once. |
Today roles are admin and member. Dedicated agent identities are represented
through approved MCP integrations when Cloud MCP is enabled; otherwise agents
operate through a local MCP client owned by a human or service account.
Provisioning routes
Section titled “Provisioning routes”Provisioning routes create organization shells and daemon records for launch onboarding flows. They require a signed-in Cloud user.
| Route | Purpose | Notes |
|---|---|---|
POST /api/provisioning/orgs/self-hosted |
Create a self-hosted org for the signed-in user. | Returns a daemon-scoped API key once for local daemon setup. |
POST /api/provisioning/orgs/cloud-hosted/comped |
Create a comped Cloud Hosted org for the signed-in user. | Requires the configured comped provisioning code outside local/test environments and provisions a managed daemon runtime. |
Vault control routes
Section titled “Vault control routes”| Route | Purpose | Notes |
|---|---|---|
GET /api/vaults |
List vaults visible to the signed-in user. | The list is sourced through each org’s daemon, not a separate Cloud vault table. |
POST /api/orgs/:orgId/vaults/relay |
Register a self-hosted relay vault. | Issues a daemon-scoped relay credential once for a self-hosted org. |
POST /api/orgs/:orgId/vaults/hosted |
Create a Hosted vault. | Asks the Hosted daemon to create the vault. |
POST /api/orgs/:orgSlug/vaults/:vaultSlug/entry |
Mint a signed vault entry assertion. | Membership is checked before the assertion is issued. |
GET /api/orgs/:orgSlug/hosted/status |
Read Hosted lifecycle status. | Only works for cloud-hosted orgs; self-hosted orgs return not_hosted_daemon. |
The important model: Cloud gates entry at the organization boundary, then routes the app to the daemon that owns the vault. Cloud should not become a second, independent vault implementation.
Relay and Hosted data plane
Section titled “Relay and Hosted data plane”Self-hosted daemons connect to Cloud through the relay using credentials issued by the control plane. Hosted daemons run under KB-1 operated infrastructure but still speak the daemon contract.
Public tunnel routes are deliberately narrow. Direct browser-shaped requests do not get to bypass signed entry and membership checks; Cloud strips client-supplied trust headers at the public boundary.
System-admin managed daemon routes
Section titled “System-admin managed daemon routes”System-admin routes require the signed-in user to be an admin in a configured Metatheory Workspace organization. They are operator routes, not customer self-service routes.
| Route | Purpose | Notes |
|---|---|---|
GET /api/admin/status |
Confirm system-admin access and configured Workspace domains. | Returns 403 for non-admin users. |
GET /api/admin/managed-daemons |
List managed daemon entitlement and runtime inventory. | Includes provider ids, desired/observed state, version metadata, and storage signals. |
POST /api/admin/orgs/:orgId/managed-daemon/comped |
Add comped managed hosting to an existing cloud-hosted org. | Provisions runtime inventory with the selected managed-daemon provider. |
POST /api/admin/managed-daemons/:orgId/image |
Roll one managed daemon to an exact image ref. | Preserves existing provider app, machine, volume, relay URL, and metadata. |
POST /api/admin/managed-daemons/:orgId/storage/check |
Query daemon storage usage through the relay. | Uses the managed daemon’s existing relay path. |