# Overview (/web/api) The hosted API is Mogplex's control plane. It is the surface the web app talks to for projects, repos, agents, assignments, automations, sandboxes, settings, and runtime inspection. This matters because it is **not** positioned like a stable versioned public platform API yet. Route shape and response details follow the product, so treat it as the live application surface behind Mogplex rather than a long-term compatibility contract. ## Read this section in order [#read-this-section-in-order] * [API Quickstart](/web/api/quickstart) for the shortest complete path from token to repo lookup, run start, event inspection, cancellation, and sandbox listing * [Authentication](/web/api/authentication) for PAT lifecycle, scopes (`read` / `write`), idempotency, and rate limits * [Errors](/web/api/errors) for the typed error envelope, code table, and retry guidance * [Runs](/web/api/runs), [Repos](/web/api/repos), [Sandboxes](/web/api/sandboxes), [MCP servers](/web/api/mcp-servers), [MCP](/web/api/mcp) for the v1 public surface (`/api/v1/mogplex/*`) * [Models](/web/api/models) for the standalone model catalog, CLI model export, and per-user enablement rules * [Working Requests](/web/api/working-requests) for concrete `curl` examples on internal control-plane routes * [Route Families](/web/api/route-families) for the broader control-plane map ## Start with safe first requests [#start-with-safe-first-requests] If you only want the most useful first calls, start here: * `GET /api/auth/user` to verify setup state, GitHub readiness, and platform access * `GET /api/settings` to inspect shared defaults like theme and default model * `GET /api/models` to inspect the visible catalog and enabled model set * `GET /api/github/installations` to confirm real GitHub App coverage * `GET /api/v1/mogplex/mcp/servers` to export the CLI-ready MCP view (PAT-only) * `GET /api/observability/stats` to inspect runtime health and cost summary See [API Quickstart](/web/api/quickstart) for a complete run path and [Working Requests](/web/api/working-requests) for broader route examples. ## How to read this API correctly [#how-to-read-this-api-correctly] Read the hosted API in this order: 1. what product surface are you trying to drive? 2. which current route family backs that surface? 3. what auth mode is that route willing to accept? If you start by assuming a clean public REST contract, you will overestimate how stable the route shape is meant to be. ## The API is product-first [#the-api-is-product-first] The easiest way to read the hosted API is: * product state first * route naming second Most routes exist because the web app needs a control-plane surface for a real product behavior, not because Mogplex has already frozen a generic external REST contract. That is why the route tree maps so closely to product areas like: * settings and auth * repos and workspaces * agents and reusable libraries * triggers, assignments, and flows * sandbox runtime and observability ## Shared auth model [#shared-auth-model] The same API is used by multiple Mogplex surfaces: * the signed-in browser app * the CLI when it talks to hosted Mogplex state * internal automated tests The current auth resolution order is: 1. `Authorization: Bearer mog_...` personal access token 2. internal Playwright auth headers used in end-to-end testing 3. browser session auth from the signed-in web app That means many routes can support both browser and CLI callers without inventing a second API namespace. ## Important auth nuance [#important-auth-nuance] Not every route treats PAT auth the same way. * Many shared read or control-plane routes accept PAT auth through the common auth helper. * Some sensitive routes intentionally require a real browser session and reject PAT auth. Token-management endpoints are the clearest example. If an API call works in the browser but fails from a PAT-backed script, check whether the route uses the session-only auth helper instead of the generic one. ## Web and CLI crossover [#web-and-cli-crossover] A few routes are intentionally designed for both surfaces: * `/api/auth/user` returns app-aware setup state, including GitHub coverage and linked-platform capability data * `/api/settings` stores shared defaults like theme and the user's selected `default_model` * `/api/mcp-servers` returns a web-oriented shape by default, and `/api/mcp-servers?format=cli` returns a CLI-oriented representation The browser-based CLI login handoff runs through `/cli-auth`, not the `/api/*` tree directly. That page validates the localhost callback requested by the CLI, asks the user for consent inside the signed-in web app, and posts the resulting token back to the CLI listener. For the model split, see [Models](/web/api/models): `/api/models` is the standalone model route, while `/api/settings` only returns or updates the selected `default_model`. ## Route families [#route-families] At a high level, the current `/api/*` tree breaks down into: * **Identity and settings**: `/api/auth/*`, `/api/settings`, `/api/models` * **Projects and GitHub state**: `/api/repos`, `/api/workspaces`, `/api/github/*` * **Reusable behavior**: `/api/agents`, `/api/agent-categories`, `/api/skills`, `/api/rules`, `/api/mcp-servers` * **Routing**: `/api/triggers`, `/api/assignments`, `/api/flows` * **Runtime**: `/api/chat`, `/api/commands`, `/api/memories`, `/api/sandbox`, `/api/observability/*` * **System plumbing**: `/api/webhooks/*`, `/api/cron/*`, `/api/test/*` See [Route Families](/web/api/route-families) for the concrete breakdown. ## Practical guidance [#practical-guidance] Prefer the web app when you want the full Mogplex workflow and setup guidance. Reach for the hosted API when you are: * extending Mogplex from internal tooling * wiring the CLI to hosted state * building adjacent product code that should behave like the web app * inspecting the current control-plane surface while implementing or debugging a feature If you depend on the hosted API directly today, document the specific routes and payloads you rely on in your own integration. The product model is still the source of truth.