Skip to content

API Reference

The complete REST surface: 28 controllers, roughly 200 endpoints, plus four SignalR hubs and the MCP transport endpoint. This is the lookup layer for §07 — MCP Architecture and the orchestrator run path described across the Developer docs — it enumerates shapes; those sections explain intent.

Endpoints are grouped into five pages by domain. The master table below maps every controller to its page.

Conventions

  • Base path. Controllers use [Route("api/[controller]")] unless a literal route is given; [controller] is the class name minus Controller. Routing is case-insensitive — /api/Settings and /api/settings match the same action. Pages below show routes as written in code.
  • Binding. All controllers carry [ApiController], so complex types bind from the request body as JSON without an explicit [FromBody], and [FromQuery] / [FromRoute] are inferred. application/json in and out unless noted (a few endpoints take multipart/form-data uploads or return a file stream).
  • Async. Most actions return Task<…>; the per-page tables flag sync vs. async.
  • DTOs. Request/response DTO type names are given. Many are declared inline in their controller; others live in Aetherium.Shared.DTOs / Aetherium.Shared.Models.

Authentication

There is no authentication or authorization anywhere in the application

No [Authorize], no [AllowAnonymous], no AddAuthentication / AddAuthorization / UseAuthentication / UseAuthorization registration exists. Every REST endpoint and every SignalR hub is unauthenticated. This matches the Engine's single-operator, trusted-LAN posture — but it means the box must not be exposed to an untrusted network without a gateway in front. The per-page tables include an Auth column for completeness; it is none for all of them.

The only request-gating in the pipeline:

  • Antiforgery (UseAntiforgery) is in the pipeline but no controller opts into validation, so external JSON callers reach the API directly. The MCP endpoint opts out explicitly (DisableAntiforgery).
  • Maintenance mode. When the MaintenanceMode system setting is true, a middleware returns 503 for nine create/build POST routes. All GETs, plus /api/health* and /api/settings*, always pass.

The x-openclaw-token header is outbound only — the Engine attaches it when delivering webhooks, set from each target's stored secret. It is not an inbound check. A couple of endpoints carry XML-comment claims of token support that the code does not implement (flagged on their pages).

PUT /api/openclaw/bridge/config rewrites appsettings.json on disk

This unauthenticated endpoint writes the bridge configuration to appsettings.json (with a timestamped backup) and reports requiresRestart: true. Treat it as a privileged operation and keep it off any reachable-from-untrusted-network surface.

Controller map

Controller Route prefix Endpoints Page
OrchestratorController api/orchestrator 14 Orchestration & Runs
FinishingController api/finishing 4 Orchestration & Runs
ProjectsController api/projects 12 Projects, Teams & Agents
RolesController api/roles 9 Projects, Teams & Agents
CompositionController api/composition 2 Projects, Teams & Agents
PromptsController api/prompts 5 Projects, Teams & Agents
TemplateController api/template 7 Projects, Teams & Agents
TeamController api/projects/{projectId}/team 1 Projects, Teams & Agents
TeamGeneratorController api/teamgenerator 2 Projects, Teams & Agents
TeamVersionController api/projects/{projectId}/versions 7 Projects, Teams & Agents
DeliverablesController api/projects/{projectId} 3 Projects, Teams & Agents
ContainerController api/container 20 Containers & Snapshots
ContainerSnapshotController api/container/snapshots 10 Containers & Snapshots
KnowledgeController api/knowledge 37 Knowledge & Memory
KnowledgeSeedingController api/projects/{id}/seed-knowledge 2 Knowledge & Memory
ConversationController api/conversation 9 Knowledge & Memory
SettingsController api/settings 4 System & Operations
HealthController api/health 2 System & Operations
MetricsController api/metrics 8 System & Operations
ModelRegistryController api/model-registry 4 System & Operations
LMStudioController api/lmstudio 8 System & Operations
InferenceController api/inference 8 System & Operations
ToolsController api/tools 2 System & Operations
ToolSecurityController api/tools (shared) 6 System & Operations
CapabilitiesController api/capabilities 3 System & Operations
AgUiController api/agui 6 System & Operations
WebhookController api/webhook 8 System & Operations
OpenClawController api/openclaw 5 System & Operations

Two controllers share /api/tools

ToolsController (schema discovery) and ToolSecurityController (approvals, audit log) both live under /api/tools on different sub-paths. They do not collide; they are two classes in one namespace.

SignalR hubs

Real-time surface alongside REST. None carry [Authorize]. SignalR options (set in Program.cs): client timeout 10 min, keep-alive 15 s, handshake timeout 30 s, max receive 10 MB.

Hub Route Client → server Server → client (selected)
NotificationHub /notificationHub JoinGroup, LeaveGroup ReceiveNotification
ProjectRunHub /projectRunHub JoinProjectGroup, LeaveProjectGroup run / step / log / AgentProgress events (per-project group)
ContainerHub /containerHub JoinDashboardGroup, JoinContainerGroup, StartLogStream, StartShellSession, SendShellInput, EndShellSession, … ReceiveContainerStats, ReceiveContainerLog, ReceiveContainerStateChange, ReceiveShellOutput, ContainerCreated, ContainerDestroyed
TeamHub /teamHub JoinProject, LeaveProject AgentStatusChanged, AgentMessageSent (group team:{projectId})

MCP transport endpoint

Verb Route Purpose
(MCP) /mcp Model Context Protocol HTTP transport, hosting the ten in-process tool classes. Mapped via MapMcp("/mcp"); antiforgery disabled. Not a REST controller.

To inspect the tool catalog over plain HTTP instead, use GET /api/tools/mcp-schemas (System & Operations).

Where to go next