Skip to content
Chapter 4 · How it works 4-10

ASP.NET Core public route contract

The canonical public surface is backend-dotnet/public-route-contract.json: 56 HTTP method/path pairs and no WebSocket route. ASP.NET Core is the only public owner, and every entry is aspnet-direct. The 31 Agent v1 routes under /agent/v1/* (including the run-independent skills catalog/preferences and the user plugin list, settings and pinned GitHub install) and the POST /host/shutdown route are active alongside the settings, session rewind, activity, status, and model routes. They cover run creation, policy/approval/input/trust, cancellation, typed command dispatch, SSE replay, and reconciliation; this is not a read-only tracer surface.

POST /agent/v1/runs/selected requires a provider/model intent and commits it with the root run. The native TUI and GUI use this route so an older Host rejects the request instead of silently ignoring a new field. The legacy create route remains available to existing clients.

POST /settings/provider/key validates a candidate OpenAI, Anthropic, Models.dev or custom endpoint credential with the provider before committing it, preserving an existing key on rejection or unavailable validation, and records the outcome in provider_key_status. It shares the normal loopback/bearer boundary and settings transaction gate. GUI does not fall back to POST /settings when an older Host lacks this route.

Session history adds /sessions/page for paged summaries, /sessions/{sessionId}/messages for bounded retained-message pages and /sessions/search for literal full-text hits. These share bearer/loopback checks and do not expose database maintenance over HTTP.

Each entry contains:

  • method, path, and transport — the stable public wire identity;
  • source — the ASP.NET source file that maps the endpoint;
  • classification — aspnet-direct;
  • winui_callers — known desktop call sites, which may be empty for routes without a WinUI caller.

aspnet-direct means ASP.NET performs the business operation itself, including GET /status and the GET /models provider catalog read from the host settings store. There is no worker-backed or Python-backed public route left; the media surfaces (voice, STT, VTS, observation) were removed in the 2026-09-13 passes.

There are no feature-selected owners, shadow reads, public forwarding routes, or alternate host mode. Unknown public paths are never sent to Python.

Reserved routes

21 entries intentionally have empty winui_callers: the message search route GET /sessions/search driven by the CLI; the TUI conversation branch route (POST /sessions/{sessionId}/fork); 14 additive /agent/v1/* routes — the 11 run routes (legacy and selected creation, run read, event stream, payload read, approvals, inputs, trust, cancel, compact, and commands) and the three policy routes (GET/POST /agent/v1/policies and DELETE /agent/v1/policies/{ruleId}) — which are driven through the Agent harness flow rather than direct WinUI callers; and the five workspace coordination routes, which external clients drive over HTTP. The remaining /agent/v1/* routes (run activities, session run listing, and the session preset read) do have direct ApiService callers. The three subagent routes have AgentRunClientAdapter callers through the typed Client library and drive the chat's read-only Subagents panel, including the bounded change review for a coding result. The three skill catalog/preferences/package routes have CustomizeView callers through SkillsApiClient, before a run exists. Package installation is an explicit user action, not an advertised model tool.

Empty winui_callers is therefore expected for these reserved routes and is not a dead-route signal.

Verification

& (Join-Path $env:RU_ROOT ".venv\Scripts\python.exe") scripts\check_aspnetcore_route_matrix.py
dotnet test backend-dotnet/RuBackend.Tests/RuBackend.Tests.csproj --no-restore `
  --filter FullyQualifiedName~PublicRouteContractTests

The checker validates count, uniqueness, schema, final classification, source existence, and route literals. The .NET test starts the real application and compares the contract against ASP.NET's EndpointDataSource; WebSocket routes are represented by their HTTP upgrade endpoints during this comparison.

Any public route change must update its endpoint tests, this JSON contract, and the WinUI caller list in the same change.