Runtime API - Mycelium docs

The runtime is a FastAPI service. Every route outside /healthz requires a tenant-scoped JWT bearer token. The full OpenAPI document is published with the runtime; this page summarizes the surface.

Health

Method	Path	Auth	Description
GET	`/healthz`	none	Build status + tenant count.
GET	`/tenants/{tenant_id}/healthz`	JWT	Per-tenant health (vault present, etc.).

Tenants

Method	Path	Auth	Description
GET	`/tenants`	JWT	List tenants visible to the calling token.
GET	`/tenants/me`	JWT	Tenant identity decoded from the calling JWT.

Memory

The typed-memory surface. See /architecture/typed-memory for category definitions.

Method	Path	Auth	Description
GET	`/memory/decisions`	JWT	List decisions for the calling tenant.
POST	`/memory/decisions`	JWT	Create a decision entry.
GET	`/memory/decisions/{sha8}`	JWT	Read a decision by SHA-8 id.
GET	`/memory/exceptions`	JWT	List exception entries.
POST	`/memory/exceptions`	JWT	Create an exception entry.
GET	`/memory/exceptions/{sha8}`	JWT	Read an exception by SHA-8 id.
GET	`/memory/facts`	JWT	List fact entries.
POST	`/memory/facts`	JWT	Create a fact entry.
GET	`/memory/facts/{sha8}`	JWT	Read a fact by SHA-8 id.
GET	`/memory/workflows`	JWT	List workflow entries.
POST	`/memory/workflows`	JWT	Create a workflow entry.
GET	`/memory/workflows/{sha8}`	JWT	Read a workflow by SHA-8 id.
GET	`/memory/relationships`	JWT	List relationship entries.
POST	`/memory/relationships`	JWT	Create a relationship entry.
GET	`/memory/relationships/{sha8}`	JWT	Read a relationship by SHA-8 id.
GET	`/memory/outcomes`	JWT	List outcomes for resolved decisions.
POST	`/memory/outcomes`	JWT	Create an outcome entry.
GET	`/memory/outcomes/{sha8}`	JWT	Read an outcome by SHA-8 id.
POST	`/memory/search`	JWT	Bi-temporal + tag + embedding query.

Webhooks

Per-tenant inbound URLs. Each source signs with its own scheme. See /connectors/index for the source list and memory-runtime-pro README for signature details.

POST /webhooks/{source}/{tenant_id}

Sources covered: slack, github, notion, linear, gmail, salesforce, microsoft365, confluence, google_workspace, servicenow, workday, sap, box, snowflake, databricks, oracle, jira, hubspot, gitlab, dropbox, zoom, adp. WhatsApp arrives via an in-process bridge (not HTTP).

Admin

Operator-only routes. JWT must carry the admin claim (the reserved all-zeros tenant).

Tenant provisioning

Method	Path	Auth	Description
POST	`/admin/tenants`	admin	Create a tenant and return an initial `tenant_admin` JWT.
GET	`/admin/tenants`	admin	List all tenants with status and role count.

curl -X POST https://<runtime>/admin/tenants \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp"}'
# → {tenant_id, tenant_name, roles, token, ttl_seconds}

JWT minting

Method	Path	Auth	Description
POST	`/admin/jwt/{tenant_id}`	admin	Mint a role-scoped JWT for an existing tenant.

RBAC roles

Method	Path	Auth	Description
GET	`/admin/roles/{tenant_id}`	admin	List the role library for a tenant.
POST	`/admin/roles/{tenant_id}`	admin	Create or replace a role.
DELETE	`/admin/roles/{tenant_id}/{role_name}`	admin	Delete a role.

Webhooks & audit

Method	Path	Auth	Description
GET	`/admin/webhooks/dead-letters/{tenant_id}`	admin	List dead-lettered webhook events.
POST	`/admin/webhooks/replay/{tenant_id}/{event_id}`	admin	Replay a specific dead-lettered event.
GET	`/admin/audit/denials/{tenant_id}`	admin	Tail recent RBAC denials for a tenant.
GET	`/admin/metrics/revenue-per-agent/{tenant_id}`	admin	Revenue-per-agent pricing metric.
GET	`/admin/dashboard`	admin	Operator HTML dashboard.

Authentication

All authenticated calls use bearer tokens:

Authorization: Bearer <jwt>

JWTs are minted via POST /admin/tenants (returns an initial token on creation), POST /admin/jwt/{tenant_id} (re-mint with specific roles), or the operator-side scripts/mint-jwt.py. Tokens are signed with MEMORY_RUNTIME_PRO_JWT_SECRET and scoped to one tenant_id.

Status codes

Code	Meaning
200	OK
201	Created
401	Bad signature or missing JWT
403	Cross-tenant write attempted
404	Tenant or entry not found
422	Schema validation failed
503	Per-tenant secret missing in env

​Health

​Tenants

​Memory

​Webhooks

​Admin

​Tenant provisioning

​JWT minting

​RBAC roles

​Webhooks & audit

​Authentication

​Status codes