> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mycelium-ai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime API

> Endpoints exposed by the paid runtime

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](/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](/connectors/index) for the source list and [memory-runtime-pro README](https://github.com/adelaidasofia/memory-runtime-pro) 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.              |

```bash theme={null}
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 |