Overview

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

• API Quickstart for the shortest complete path from token to repo lookup, run start, event inspection, cancellation, and sandbox listing
• Authentication for PAT lifecycle, scopes (read / write), idempotency, and rate limits
• Errors for the typed error envelope, code table, and retry guidance
• Runs, Repos, Sandboxes, MCP servers, MCP for the v1 public surface (/api/v1/mogplex/*)
• Models for the standalone model catalog, CLI model export, and per-user enablement rules
• Working Requests for concrete curl examples on internal control-plane routes
• Route Families for the broader control-plane map

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 for a complete run path and Working Requests for broader route examples.

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 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

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

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

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: /api/models is the standalone model route, while /api/settings only returns or updates the selected default_model.

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 for the concrete breakdown.

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.