Admin API
Operator-facing HTTP surfaces that ship with the Bigwave API process. Every route below is bearer-token gated against BIGWAVE_ADMIN_TOKEN (or the proxy-headers principal, when BIGWAVE_AUTH=proxy_headers) and is workspace-scoped through the calling principal.
These endpoints sit alongside the OpenAI-shaped /v1/* chat surface documented in the How-to guides and the Configuration reference. They are intended for ops tooling, dashboards, and the in-tree bw CLI — not chat clients.
Surface map
| Surface | Purpose |
|---|---|
| Adapters | LoRA adapter registry — list, fetch, delete trained adapters. |
| API tokens | Mint, list, and revoke per-workspace API tokens for /v1/* clients. |
| Audit | Read the append-only audit log for the workspace. |
| Catalog | Federated model catalog search (HuggingFace / Ollama Hub / Modelscope). |
| Channels | CRUD over Telegram / Slack / Discord / Web channel bindings. |
| Cost | Workspace cost rollups and the per-model price table. |
| Datasets | Upload, list, paginate, export, and delete workspace datasets (SFT / DPO). |
| Evals | Submit, stream, and fetch evaluation runs and reports. |
| Feedback aggregation | Roll up thumbs events and project them into a DPO dataset. |
| Guardrails policy | CRUD over the workspace's input/output guardrail policy. |
| Inference | Paginated read of the inference lifecycle log. |
| Knowledge bases | Ingest, query, and delete documents in workspace-scoped RAG collections. |
| MCP | Model Context Protocol over HTTP — list and invoke Bigwave tools. |
| Models | Load, unload, list, and adapter-activate replicas on the running engine. |
| Rate limit | Inspect and reset the per-workspace token bucket. |
| Sandbox policy | CRUD over the per-workspace sandbox policy used by the agent runtime. |
| Shadow mode | Toggle the secondary model that the gateway fans out to in the background. |
| Training | Submit, stream, and cancel fine-tuning jobs. |
| Uploads | Extract text from a single file for inline RAG injection. |
| Webhooks | Inbound webhook receivers from third-party channels. |
| Workspace tools | Register user-defined tool definitions that merge into the agent-runtime registry. |
| Workspaces | CRUD over the workspaces table — the unit of multi-tenant isolation. |
Conventions
Authentication. Send Authorization: Bearer $BIGWAVE_ADMIN_TOKEN. Omitting the header returns 401.
Workspace fence. Every admin route resolves the workspace from the bearer principal — query strings or bodies that try to override it are ignored. Cross-tenant lookups return 404 (not 403) so existence does not leak. See the workspace fence concept for the broader contract.
503 Service Unavailable. Several admin surfaces depend on optional lifespan wiring (channel store, replica manager, federated catalog). When the relevant component is not initialised on app.state, the route returns 503 with an explanatory detail.
Audit trail. Mutating routes (POST / DELETE) write to audit_log via AuditLogRepository when one is wired; reads do not.
CLI wrappers
Most surfaces are also exposed by the bw CLI in the repo (packages/cli/). Where the wrapper exists, the per-surface page calls it out — operators usually prefer bw model loaded over a hand-rolled curl.