API Quickstart

Use this quickstart when you want to drive Mogplex from a script, internal tool, CI job, or dashboard.

The hosted API is still product-first. It is the control plane behind the web app and CLI, not a frozen compatibility contract for every internal route. For the most stable external surface, start with /api/v1/mogplex/*.

Prerequisites

Before calling the API:

1. sign in to the web app
2. create a personal access token in Settings
3. make sure the repo is imported and visible in Projects
4. make sure the token has read for list/detail calls and write for run starts or cancellation

Set these once in your shell:

export MOGPLEX_BASE_URL="https://www.mogplex.com"
export MOGPLEX_TOKEN="mog_..."

Every request below uses the same bearer header:

-H "Authorization: Bearer $MOGPLEX_TOKEN"

1. Verify the account

Start with account state. This tells you whether the token works and whether GitHub, managed model access, and managed sandbox access look ready.

curl -sS \
  -H "Authorization: Bearer $MOGPLEX_TOKEN" \
  "$MOGPLEX_BASE_URL/api/auth/user"

If this returns 401, fix the token before debugging repos, runs, models, or sandboxes.

2. List repos

Use the v1 repos route to find the repoId required by run starts.

curl -sS \
  -H "Authorization: Bearer $MOGPLEX_TOKEN" \
  "$MOGPLEX_BASE_URL/api/v1/mogplex/repos?q=acme&limit=20"

The response includes the repo id, full name, default branch, and root directory when Mogplex has one stored.

{
  "ok": true,
  "data": {
    "repos": [
      {
        "id": "8f3a2b1c-1234-4abc-9def-1234567890ab",
        "full_name": "acme/web",
        "default_branch": "main",
        "root_directory": "apps/web"
      }
    ]
  }
}

If the repo is missing, check GitHub App Coverage and Projects before starting a run.

3. Check model availability

Use the model route when your script needs to show choices or confirm the account has at least one enabled model.

curl -sS \
  -H "Authorization: Bearer $MOGPLEX_TOKEN" \
  "$MOGPLEX_BASE_URL/api/models?format=cli"

Use Available Models for the product-facing model guide and API Models for the route contract.

4. Start a run

Starting a run is a write operation and requires an Idempotency-Key.

RUN_RESPONSE=$(curl -sS \
  -X POST \
  -H "Authorization: Bearer $MOGPLEX_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "repoId": "8f3a2b1c-1234-4abc-9def-1234567890ab",
    "prompt": "Inspect the failing test suite and propose the smallest fix.",
    "harness": "codex",
    "baseBranch": "main",
    "createBranch": true,
    "rootDirectory": "apps/web"
  }' \
  "$MOGPLEX_BASE_URL/api/v1/mogplex/runs")

echo "$RUN_RESPONSE"

Representative response:

{
  "ok": true,
  "data": {
    "runId": "run-uuid",
    "status": "pending",
    "eventsUrl": "/api/v1/mogplex/runs/run-uuid/events",
    "cancelUrl": "/api/v1/mogplex/runs/run-uuid/cancel",
    "branch": {
      "base": "main",
      "working": "mogplex/run/YYYY-MM-DD/inspect-tests",
      "createBranch": true
    },
    "replayed": false
  }
}

Use a fresh idempotency key per logical run start. Reuse the same key only when retrying the same request body.

5. Inspect the run

Fetch current run state:

curl -sS \
  -H "Authorization: Bearer $MOGPLEX_TOKEN" \
  "$MOGPLEX_BASE_URL/api/v1/mogplex/runs/run-uuid"

Fetch recent events:

curl -sS \
  -H "Authorization: Bearer $MOGPLEX_TOKEN" \
  "$MOGPLEX_BASE_URL/api/v1/mogplex/runs/run-uuid/events?limit=100"

Terminal statuses are:

Non-terminal statuses such as pending and streaming mean the run is still being allocated or is actively producing events.

6. Cancel a run

Cancellation is a write operation.

curl -sS \
  -X POST \
  -H "Authorization: Bearer $MOGPLEX_TOKEN" \
  "$MOGPLEX_BASE_URL/api/v1/mogplex/runs/run-uuid/cancel"

Cancellation is idempotent. If the run is already terminal, the endpoint returns the terminal state without starting another cancellation path.

7. Inspect sandboxes

Use sandboxes when the runtime or preview is the thing you need to inspect.

curl -sS \
  -H "Authorization: Bearer $MOGPLEX_TOKEN" \
  "$MOGPLEX_BASE_URL/api/v1/mogplex/sandboxes?repo_id=8f3a2b1c-1234-4abc-9def-1234567890ab&status=running"

The v1 API currently lists sandboxes. Lifecycle operations such as stop, pause, resume, or delete belong in the web UI until the lifecycle routes are exposed.

First error map

Read next