The foxctl API server is the HTTP surface behind foxctl web serve. It exposes runtime state, agent management, room coordination, orchestration, companion chat, and retrieval endpoints under the base path /api.
Protocol-style command envelopes for command-oriented handlers. These follow the Protocol v1 envelope shape with version, status, command, data, meta, and error fields.
JSON resource responses for list/detail style endpoints.
Large payloads may be artifactized through CAS, especially in orchestration and other high-volume responses. When a response exceeds the CAS threshold, the envelope contains data.summary plus a data.artifact pointer instead of the full payload inline.
GET /api/events remains the global invalidation/event feed used by broad UI surfaces.
GET /api/rooms/{id}/events?workspace_id=... is the stable room-scoped SSE surface for room clients.
Room mutation routes are actor-authorized: room patch and full member replacement require coordinator access.
Member transport and binding updates are self-service only for the target participant unless the caller has coordinator access.
Role-changing member binding updates are coordinator-only even when the caller is updating their own binding.
Room member payloads expose delivery_binding as the canonical binding/routing record. Legacy top-level fields (backend, session, pane_id, transport_endpoint, transport_kind) are still mirrored for compatibility.
Room status responses expose last_delivery_trace from the persisted room-loop row. This trace records the chosen binding, transport endpoint/kind, fallback attempt, outcome, and cursor movement for the latest delivery decision.
Room reminder schedules are durable room-loop state. Acknowledging one emitted reminder does not cancel the schedule. Reminders can also stop automatically when linked task_id, story_id, or milestone_id work is satisfied.
The API server is hybrid: some handlers are classic storage/resource handlers, while orchestration, ask state, and runtime tree inspection now intersect with v2 projections and Jido-backed runtime data.
/api/agents/* is a mix of local store operations, daemon-backed agent control, and newer runtime-state inspection helpers.
/api/orchestration/* is the clearest current v2/Jido-backed HTTP surface.
/api/companion/* provides the full companion chat and memory surface.
All routes that modify state enforce principal propagation through the auth middleware. See Auth and identity for how principals, Casbin policies, and the OAuth broker work.
The canonical OpenAPI spec lives at docs/general/api-server.openapi.yaml. It defines request/response schemas, envelope shapes, and parameter types. Note that the spec still references /api/v1 in server URLs for backward compatibility, but the live server serves /api/*.
