Repository navigation
API Reference
Every route is served by
MasterControlRuntime.cpp
and bound to the loopback interface. The shell, browser admin UI, and the
feature-test harness all consume the same routes — there is no second API.
| Method | Route | Returns |
|---|---|---|
GET |
/api/health |
Service health and readiness snapshot |
GET |
/api/dashboard |
Composite payload powering the desktop shell + browser dashboard |
GET |
/api/config |
Current persisted configuration |
GET |
/api/providers |
Provider catalog, credential posture, and assignments |
GET |
/api/exports |
Export inventory + handoff artifacts |
GET |
/api/forsetti/surface |
Forsetti surface model used by both UIs |
GET |
/api/forsetti/modules |
Module catalog metadata |
GET |
/api/install/history |
Install + import execution history |
GET |
/api/beacon |
LAN beacon advertisement payload |
GET |
/api/activity?since={id} |
Activity ring events newer than id
|
{
"highWaterMarkId": 174,
"events": [
{
"id": 174,
"kind": "api",
"timestampUtc": "2026-04-11T17:42:13.812Z",
"method": "POST",
"target": "/api/providers/auto-connect",
"statusCode": 200,
"latencyMs": 184,
"summary": "auto-connect openai succeeded"
}
]
}The ring buffer holds the last 512 events with monotonically increasing IDs. The shell polls every two seconds while focused.
| Method | Route | Purpose |
|---|---|---|
POST |
/api/providers/auto-connect |
Add an AI provider end-to-end (capability resolution → discovery → DPAPI → assignment) |
Request body:
{
"kind": "openai",
"credentials": { "api_key": "sk-..." },
"assignmentTargetIds": ["planner", "coder"],
"discoverModels": true
}Response body (AutoConnectResult):
{
"succeeded": true,
"providerId": "openai-7f3a",
"summary": "Auto-Connect completed in 184 ms",
"totalLatencyMs": 184,
"steps": [
{ "name": "Resolve capability", "ok": true, "latencyMs": 1 },
{ "name": "Generate provider id", "ok": true, "latencyMs": 0 },
{ "name": "Probe remote endpoint", "ok": true, "latencyMs": 142 },
{ "name": "Discover models", "ok": true, "latencyMs": 36 },
{ "name": "Persist credentials (DPAPI)", "ok": true, "latencyMs": 2 },
{ "name": "Register provider", "ok": true, "latencyMs": 1 },
{ "name": "Apply role assignments", "ok": true, "latencyMs": 2 }
],
"discoveredModels": [
{ "id": "gpt-4o", "displayName": "GPT-4o", "selected": true }
]
}See Auto-Connect AI for the full pipeline walkthrough.
| Method | Route | Purpose |
|---|---|---|
GET |
/api/clu |
CLU posture, findings, and current governance state |
GET |
/api/clu/tools |
Published governance tool descriptors |
GET |
/api/clu/apple-operations |
Apple job queue + history |
POST |
/api/clu/execute |
Execute a CLU governance operation |
POST |
/api/clu/apple-operations/cancel |
Cancel a queued Apple operation |
All endpoints are backed by the CommandLogicUnitModule Forsetti service module
(com.mastercontrol.command-logic-unit).
| Method | Route | Purpose |
|---|---|---|
GET |
/api/platform-services |
Combined gateway + governance + host inventory |
GET |
/api/platform-services/gateways |
Platform gateway summary |
GET |
/api/platform-services/governance |
Platform governance lane summary |
GET |
/api/platform-services/apple-hosts |
Registered Apple remote hosts + readiness |
POST |
/api/platform-services/apple-hosts |
Add or update an Apple host |
POST |
/api/platform-services/apple-hosts/remove |
Remove an Apple host |
GET |
/api/platform-services/config/{platform} |
Platform-specific client configuration |
GET |
/mcp/gateway/{platform} |
Gateway document for windows / macos / ios
|
GET |
/mcp/governance/{platform} |
Governance document for the same set |
POST |
/mcp/governance/{platform} |
Execute a platform governance tool call |
All mutating routes refresh inventory asynchronously via
IRuntimeInventoryService::refreshAsync() so admin calls return immediately
instead of blocking on the 35+ endpoint TCP probe loop.
| Method | Route | Purpose |
|---|---|---|
POST |
/api/runtime/mcp-servers |
Create or update a custom MCP server |
POST |
/api/runtime/mcp-servers/remove |
Remove a custom MCP server |
POST |
/api/runtime/subagents |
Create or update a sub-agent |
POST |
/api/runtime/subagents/remove |
Remove a sub-agent |
POST |
/api/providers/groups |
Create or update a provider group |
POST |
/api/providers/groups/remove |
Remove a provider group |
POST |
/api/providers/assignments |
Apply provider routing assignments |
POST |
/api/providers/credentials |
Save provider credential material (DPAPI) |
POST |
/api/providers/execute |
Execute a provider-backed request |
| Method | Route | Purpose |
|---|---|---|
POST |
/api/install/package |
Import or deploy a package artifact |
POST |
/api/install/repo |
Import from a Git or bootstrap repository |
POST |
/api/install/zip |
Import from a zip bundle |
Every mutating route returns a uniform OperationResult:
{
"succeeded": true,
"summary": "MCP server feature-test-mcp upserted",
"errorMessage": "",
"warnings": []
}On failure, succeeded is false, errorMessage is populated, and the HTTP
status reflects the failure category (400 / 404 / 409 / 500).
See also: Architecture · Auto-Connect AI · Telemetry & Activity
Source for this wiki is maintained under docs/wiki/ in the Master-Control-Orchestration-Server repository.
Setup
Connect Clients
Operate
- Daily Operations
- Dashboard
- Telemetry and Activity
- Gateway
- Worker Pools
- Sub-Agents
- Governance
- CLU Governance
- Privileges
Maintain
Troubleshoot
Reference