Mogplex Docs
Reference

Runs

POST /api/v1/mogplex/runs starts an agent run in a cloud sandbox. GET the run, tail its events, and cancel it via the companion endpoints. This is the most-used part of the v1 API.

Four endpoints cover the run lifecycle:

EndpointMethodScopePurpose
/api/v1/mogplex/runsPOSTwriteStart a run
/api/v1/mogplex/runs/{runId}GETreadGet a run's current state
/api/v1/mogplex/runs/{runId}/eventsGETreadList run events (sanitized, oldest-first)
/api/v1/mogplex/runs/{runId}/cancelPOSTwriteRequest cancellation

Start a run

POST /api/v1/mogplex/runs

Required headers:

Request body:

type StartMogplexApiRunRequest = {
  repoId: string;                          // Required — get from GET /repos
  prompt: string;                          // Required — max 100,000 chars
  harness?: "codex" | "claude-code";       // Default: "codex"
  baseBranch?: string;                     // Default: repo default_branch (or "main")
  workingBranch?: string;                  // Default: baseBranch (or a generated name when createBranch=true)
  createBranch?: boolean;                  // If true, create/use the generated working branch
  rootDirectory?: string | null;           // Monorepo subpath
  conversationId?: string | null;          // Attach to an existing conversation
  workspaceSessionId?: string | null;      // Attach to an existing workspace session
  mode?: string | null;                    // Mode hint for the runtime
};

Example

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

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": "Refactor the auth module to use bearer tokens instead of cookies.",
    "harness": "codex",
    "baseBranch": "main",
    "createBranch": true
  }' \
  "$MOGPLEX_BASE_URL/api/v1/mogplex/runs"

Response (HTTP 202 Accepted):

{
  "ok": true,
  "data": {
    "runId": "run-uuid",
    "aiCallId": "call-uuid",
    "sandboxRecordId": "sandbox-record-uuid",
    "sandboxId": null,
    "repoId": "8f3a2b1c-1234-4abc-9def-1234567890ab",
    "harness": "codex",
    "status": "pending",
    "branch": {
      "base": "main",
      "working": "mogplex/run/2026-05-17/refactor-auth",
      "createBranch": true
    },
    "rootDirectory": null,
    "eventsUrl": "/api/v1/mogplex/runs/run-uuid/events",
    "cancelUrl": "/api/v1/mogplex/runs/run-uuid/cancel",
    "createdAt": "2026-05-17T10:14:00.000Z",
    "updatedAt": "2026-05-17T10:14:00.000Z",
    "error": null,
    "runtime": {
      "provider": "trigger",
      "runId": "trigger-run-uuid"
    },
    "replayed": false
  }
}

If you POST the same body with the same Idempotency-Key, replayed becomes true and runId matches the first call.

Status values

StatusMeaning
pendingAccepted, waiting on sandbox + runtime allocation
streamingAgent is actively producing events
successTerminal — agent completed without error
failedTerminal — agent or sandbox failed
cancelledTerminal — cancellation requested and acknowledged

Errors

CodeHTTPCause
UNAUTHORIZED401Missing/invalid PAT
FORBIDDEN403PAT lacks write scope
BAD_REQUEST400Missing Idempotency-Key, missing repoId/prompt, invalid harness, invalid branch name
NOT_FOUND404repoId doesn't belong to the caller
IDEMPOTENCY_CONFLICT409Same key used with a different body
RATE_LIMITED429Per-PAT (60/min) or per-user run-start budget exceeded
SERVICE_UNAVAILABLE503Limit-check backend unavailable
INTERNAL_ERROR500Unexpected server error

See Errors.

Get a run

GET /api/v1/mogplex/runs/{runId}

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

Response:

{
  "ok": true,
  "data": {
    "run": {
      "runId": "run-uuid",
      "status": "streaming",
      "harness": "codex",
      "repoId": "8f3a2b1c-...",
      "branch": { "base": "main", "working": "feat/x", "createBranch": true },
      "sandboxId": "vsb_abc",
      "createdAt": "2026-05-17T10:14:00.000Z",
      "updatedAt": "2026-05-17T10:15:30.000Z",
      "error": null,
      "eventsUrl": "/api/v1/mogplex/runs/run-uuid/events",
      "cancelUrl": "/api/v1/mogplex/runs/run-uuid/cancel",
      "runtime": { "provider": "trigger", "runId": "..." }
    }
  }
}

Errors: UNAUTHORIZED (401), NOT_FOUND (404), RATE_LIMITED (429), INTERNAL_ERROR (500).

List run events

GET /api/v1/mogplex/runs/{runId}/events

Returns the event stream for a run, oldest first. Useful for polling, replay, or tailing from CI.

Query parameters:

ParamTypeDefaultNotes
limitinteger1001–200
curl -sS \
  -H "Authorization: Bearer $MOGPLEX_TOKEN" \
  "$MOGPLEX_BASE_URL/api/v1/mogplex/runs/run-uuid/events?limit=50"

Response:

{
  "ok": true,
  "data": {
    "run": { /* same shape as GET /runs/{runId} */ },
    "events": [
      {
        "id": "event-uuid",
        "type": "stream_started",
        "toolName": null,
        "message": "Agent started",
        "payload": {},
        "createdAt": "2026-05-17T10:14:10.000Z"
      },
      {
        "id": "event-uuid-2",
        "type": "tool_call",
        "toolName": "edit_file",
        "message": "Editing src/auth.ts",
        "payload": { "path": "src/auth.ts" },
        "createdAt": "2026-05-17T10:14:15.000Z"
      }
    ]
  }
}

Event payloads are sanitized server-side: sensitive keys (env vars, GitHub tokens, AI billing source) are redacted; strings over 2,000 chars are truncated; arrays/objects are capped at 25 items / depth 3 / 20 KB JSON. The goal is safe inclusion in dashboards and logs without leaking secrets.

Polling for terminal status

Polling pattern in pseudocode:

loop:
  events = GET /runs/{id}/events
  emit events.events (de-duped by id)
  if events.run.status in {success, failed, cancelled}: break
  sleep 1.5s

The CLI's mogplex runs events <id> --follow implements this with a 1.5s poll interval and a configurable --timeout (default 1800s).

Errors: UNAUTHORIZED (401), NOT_FOUND (404), RATE_LIMITED (429), INTERNAL_ERROR (500).

Cancel a run

POST /api/v1/mogplex/runs/{runId}/cancel

Idempotent. Requesting cancellation on a run that's already terminal returns the terminal state with no side effects.

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

Response:

{
  "ok": true,
  "data": {
    "run": { /* MogplexApiRunDetail */ },
    "status": "cancellation_requested"
  }
}

Possible status values:

  • cancellation_requested — agent signaled, will reach cancelled shortly
  • already_terminal — run was already in success / failed / cancelled

Errors: UNAUTHORIZED (401), FORBIDDEN (403, missing write scope), NOT_FOUND (404), CONFLICT (409, sandbox unreachable), INTERNAL_ERROR (500).

CLI equivalents

# Start
mogplex run --repo <id> --harness codex "Refactor auth module"

# Inspect
mogplex runs get <id>
mogplex runs events <id> --follow --timeout 600
mogplex runs cancel <id>

See Headless runs for a fuller walkthrough.

  • Errors — full error code table
  • Authentication — PAT scopes and idempotency
  • MCP — the same surface exposed as a JSON-RPC MCP server
Edit on GitHub

API Models

Previous Page

API Repos

Next Page

On this page

Start a runExampleStatus valuesErrorsGet a runList run eventsPolling for terminal statusCancel a runCLI equivalentsRead next