# Route Families (/web/api/route-families) The hosted API is easiest to understand when you read it as a control plane, not as a generic public REST surface. Most route groups map directly to a product area. If you want copy-paste examples first, go to [Working Requests](/web/api/working-requests) and then come back here. ## v1 public surface [#v1-public-surface] Representative routes: * `/api/v1/mogplex/repos` (GET) * `/api/v1/mogplex/sandboxes` (GET) * `/api/v1/mogplex/runs` (POST) * `/api/v1/mogplex/runs/{runId}` (GET) * `/api/v1/mogplex/runs/{runId}/events` (GET) * `/api/v1/mogplex/runs/{runId}/cancel` (POST) * `/api/v1/mogplex/mcp/servers` (GET) * `/api/v1/mogplex/mcp` (POST, JSON-RPC) This is the stable, **PAT-only** surface for headless callers — the CLI's `mogplex repos|run|runs|sandboxes` commands, the in-app MCP server, and any third-party integration. Every endpoint returns the same typed envelope documented at [Errors](/web/api/errors), and mutations enforce the `write` scope per [Authentication](/web/api/authentication). Good first calls in this family: * `GET /api/v1/mogplex/repos` to discover repo IDs * `POST /api/v1/mogplex/runs` (with `Idempotency-Key`) to start an agent run * `GET /api/v1/mogplex/runs/{id}/events` to tail it Read [Runs](/web/api/runs) for a full walkthrough. This family is intentionally narrower than the internal control-plane families below — it covers headless agent-run automation and nothing else. Other behaviors stay on the internal `/api/*` surface until they have a stable public contract. ## Identity and setup [#identity-and-setup] Representative routes: * `/api/auth/*` * `/api/auth/user` * `/api/settings` * `/api/settings/keys` * `/api/settings/api-keys` * `/api/models` These routes answer questions like: * who is the current user in Mogplex terms? * what GitHub/App/Vercel setup state should the UI show? * what access tokens, defaults, managed access, and models are available? One important implementation detail: * the canonical model catalog lives in Supabase `ai_models` * per-user enabled or disabled state lives in `user_model_preferences` * the selected default model id lives on the profile row * `/api/models` is the standalone route that exposes the catalog and user-visible enabled model set * `/api/settings` resolves the stored profile `default_model` against that catalog and enabled-state rules before returning it See [Models](/web/api/models) for the route-specific GET, CLI-format, and PATCH behavior. That means the split is: * use `/api/models` when you need models * use `/api/settings` when you need the selected default model preference Good first calls in this family: * `GET /api/auth/user` for overall readiness * `GET /api/settings` for shared user defaults * `GET /api/models` for the standalone model catalog and enabled model set This family matters because setup state is first-class in the product. The UI does not just assume the account is ready. ## Projects, repos, and GitHub coverage [#projects-repos-and-github-coverage] Representative routes: * `/api/repos` * `/api/repos/[id]` * `/api/workspaces` * `/api/workspaces/[id]` * `/api/github/installations` * `/api/github/repos` * `/api/github/owners` * `/api/github/pulls` These routes manage the imported repo graph the rest of Mogplex builds on. Good first calls in this family: * `GET /api/github/installations` when webhook-backed routing looks empty * `GET /api/repos` when Projects state itself looks wrong If routing, repo visibility, monorepo structure, or sandbox ownership feels wrong, this is often the state layer to inspect first. ## Connections and reusable libraries [#connections-and-reusable-libraries] Representative routes: * `/api/connections` * `/api/connections/[id]` * `/api/connections/oauth` * `/api/mcp-servers` * `/api/mcp-servers/[id]` * `/api/agents` * `/api/agents/roster` * `/api/agents/generate` * `/api/agent-categories` * `/api/skills` * `/api/skills/registry` * `/api/skills/vercel-docs` * `/api/rules` This is the reusable behavior layer behind: * agent definitions * categories * MCP server sync * connection health * rules, skills, and shared context libraries Good first calls in this family: * `GET /api/mcp-servers?format=cli` when the CLI should mirror hosted MCP state * `GET /api/connections` when tool access feels configured wrong If the product feels "configured wrong" rather than "running wrong", this is often the route family involved. ## Routing surfaces [#routing-surfaces] Representative routes: * `/api/triggers` * `/api/assignments` * `/api/flows` * `/api/flows/[id]` These routes back the three durable routing models in Mogplex: * installation-scoped event routing * repo-scoped standing work * multi-step workflow graphs They matter because Mogplex treats event routing, repo responsibility, and workflow orchestration as different product models instead of one overloaded object. Good first calls in this family: * `GET /api/flows` to list existing automations * `POST /api/flows` to create a new automation shell for one installation ## Conversations, memory, and live agent work [#conversations-memory-and-live-agent-work] Representative routes: * `/api/chat` * `/api/conversations` * `/api/commands` * `/api/memories` * `/api/memories/actions` These routes support active work once the user is already inside a workspace or live session. This family is about ongoing agent interaction, not just setup or routing. ## Sandbox runtime and observability [#sandbox-runtime-and-observability] Representative routes: * `/api/sandbox` * `/api/sandbox/[id]` * `/api/observability/stats` * `/api/observability/calls` * `/api/observability/call-events` * `/api/observability/jobs` * `/api/observability/automation-events` * `/api/observability/automation-failures` * `/api/observability/tool-calls` If the routing surface answers "what should run?", these routes answer: * what is running now? * what call or job failed? * which sandbox was involved? * how much did it cost? * what tool calls happened? Good first calls in this family: * `GET /api/observability/stats` for compressed health and cost signals * `GET /api/sandbox/[id]` when you already know the sandbox you need to inspect ## System plumbing and internal operations [#system-plumbing-and-internal-operations] Representative routes: * `/api/webhooks/github` * `/api/cron/*` * `/api/jobs` * `/api/jobs/process` * `/api/test/*` * `/api/migrate` These are not the main user-facing control surfaces, but they matter when you are debugging the product as a whole. This family includes: * webhook ingestion * scheduled repair and sync jobs * internal processing routes * test helpers * migration and maintenance paths You usually do not start in this family unless you are debugging Mogplex itself. ## A useful mental model [#a-useful-mental-model] When you are trying to find the right route family, ask one question first: **Is this about setup, reusable definition, routing, active execution, or system maintenance?** That usually narrows the relevant API surface immediately. ## Product-first, not platform-first [#product-first-not-platform-first] This is the key architectural point: the Mogplex API is still organized around product behavior, not around a frozen versioned public contract. So if you build on it directly: * depend on specific routes intentionally * document the exact payloads you rely on * expect the product model to remain the source of truth