# API Quickstart (/web/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 [#prerequisites] Before calling the API: 1. sign in to the web app 2. create a personal access token in [Settings](/web/settings) 3. make sure the repo is imported and visible in [Projects](/web/spaces) 4. make sure the token has `read` for list/detail calls and `write` for run starts or cancellation Set these once in your shell: ```bash export MOGPLEX_BASE_URL="https://www.mogplex.com" export MOGPLEX_TOKEN="mog_..." ``` Every request below uses the same bearer header: ```bash -H "Authorization: Bearer $MOGPLEX_TOKEN" ``` ## 1. Verify the account [#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. ```bash 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 [#2-list-repos] Use the v1 repos route to find the `repoId` required by run starts. ```bash 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. ```json { "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](/web/guides/github-app-coverage) and [Projects](/web/spaces) before starting a run. ## 3. Check model availability [#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. ```bash curl -sS \ -H "Authorization: Bearer $MOGPLEX_TOKEN" \ "$MOGPLEX_BASE_URL/api/models?format=cli" ``` Use [Available Models](/web/models) for the product-facing model guide and [API Models](/web/api/models) for the route contract. ## 4. Start a run [#4-start-a-run] Starting a run is a write operation and requires an `Idempotency-Key`. ```bash 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: ```json { "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 [#5-inspect-the-run] Fetch current run state: ```bash curl -sS \ -H "Authorization: Bearer $MOGPLEX_TOKEN" \ "$MOGPLEX_BASE_URL/api/v1/mogplex/runs/run-uuid" ``` Fetch recent events: ```bash curl -sS \ -H "Authorization: Bearer $MOGPLEX_TOKEN" \ "$MOGPLEX_BASE_URL/api/v1/mogplex/runs/run-uuid/events?limit=100" ``` Terminal statuses are: | Status | Meaning | | ----------- | ------------------------------------------- | | `success` | The run completed without error | | `failed` | The agent or sandbox failed | | `cancelled` | Cancellation was requested and acknowledged | Non-terminal statuses such as `pending` and `streaming` mean the run is still being allocated or is actively producing events. ## 6. Cancel a run [#6-cancel-a-run] Cancellation is a write operation. ```bash 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 [#7-inspect-sandboxes] Use sandboxes when the runtime or preview is the thing you need to inspect. ```bash 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 [#first-error-map] | Symptom | Start here | | ------------------------------- | ------------------------------------------------------------------ | | `401 UNAUTHORIZED` | Token is missing, invalid, expired, or revoked | | `403 FORBIDDEN` | Token works but lacks the required scope | | `400 BAD_REQUEST` on run start | Check `Idempotency-Key`, `repoId`, `prompt`, branch, and harness | | `404 NOT_FOUND` for repo or run | The id does not belong to the authenticated user | | `409 IDEMPOTENCY_CONFLICT` | Same idempotency key was reused with a different body | | `429 RATE_LIMITED` | Respect `Retry-After` and reduce request or run-start rate | | No repo appears | Fix GitHub App coverage or repo import before API work | | No model is usable | Check [Available Models](/web/models) and plan-backed model access | ## Read next [#read-next]