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

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

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

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.
`DELETE /api/orgs/:orgId`	Delete an unbilled organization.	Admin route; requires the exact org name, tears down hosted infrastructure first, and blocks orgs with Stripe history.
`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

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

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

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

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. The single-daemon image route also accepts the scoped MANAGED_DAEMON_ADMIN_TOKEN bearer credential so automation does not need to copy a browser session. That credential is rejected by every other admin route, including fleet rollout.

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/managed-daemons/:orgId/image`	Roll one managed daemon to an exact image ref.	Preserves existing provider app, machine, volume, relay URL, and metadata.
`GET /api/admin/orgs/:orgId/mutations`	List content-blind, actor-attributed administrative mutations.	System admins only.
`POST /api/admin/orgs/:orgId/managed-daemon/comped`	Grant initial complimentary Hosted access.	Requires an operation id, internal reason, and exact org-slug confirmation; writes an audit operation.
`POST /api/admin/managed-daemons/:orgId/storage/check`	Query daemon storage usage through the relay.	Requires an operation id, reason, and exact org-slug confirmation; may wake the runtime and writes an audit.
`POST /api/admin/orgs/:orgId/mutation-claim/recover`	Recover one stale administrative execution claim.	Requires the exact action and owner plus confirmation that the original Worker stopped.

For both audited mutation routes, generate a unique operationId. It is bound to the exact actor, target, reason, and action parameters; reuse it after operation_retryable, operation_in_progress, a transport error, or an uncertain internal error. operation_failed is terminal and requires a new operation id. Replays are idempotent: the API returns a recorded success or reconciles an executing request only from a runtime marker carrying that exact operation id. Otherwise it returns operation_in_progress instead of repeating the mutation. Execution claims carry a 10-minute diagnostic timestamp but are never stolen automatically. A stale claim requires explicit recovery after proving the original worker stopped. An active complimentary-grant claim also fences billing reservations and organization deletion until the managed-runtime provisioning lease is installed or the grant fails. Recovery compare-deletes only an expired claim matching expectedOwner; after recovery, retry the original operation id rather than creating a replacement.

Roll one managed daemon from the CLI

Configure MANAGED_DAEMON_ADMIN_TOKEN as a Worker secret and inject the same value into the operator shell from the approved secret manager. Do not place it in a command argument, repository file, or shell history.

First validate the exact environment, organization, and image without making a request:

pnpm managed-daemon:rollout-image:production -- \
  --org-id org_0123456789abcdef0123456789abcdef \
  --image-ref registry.fly.io/kb1-md-prod-daemon:production-example \
  --confirm-org-id org_0123456789abcdef0123456789abcdef \
  --dry-run

Remove --dry-run to perform the update. The command fails unless the image uses the selected environment’s registry repository, the confirmation exactly matches the organization, and the API reports that the same organization and image reached running. The API performs relay-key rotation, Fly convergence, D1 runtime reconciliation, and lifecycle-event recording as one managed operation.