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 and then come back here.

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, and mutations enforce the write scope per 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 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

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

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

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

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

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

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

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

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

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