API overview
The Midcore backend is a FastAPI application for automation, CI, and integrations: agent runs, gates, evidence, tenancy, and the large autonomy module surface.
OpenAPI and interactive docs
Non-production deployments expose machine-readable and browsable API documentation on the same origin as the API (not the Next.js site). Production disables Swagger/ReDoc/OpenAPI JSON to reduce IP exposure:
GET /openapi.json— OpenAPI 3 schemaGET /docs— Swagger UIGET /redoc— ReDoc
Example: if your API base is https://api.example.com, open https://api.example.com/docs. From the web app in the browser, API calls are usually proxied via /api/backend/* (see App vs autonomy API).
Automation and agent surface
Agent orchestration, studio runs, streaming, smart gates, and reliability helpers live under the /api/v1/autonomy/ prefix on the FastAPI server. Examples (all require auth in normal deployments):
| Method | Path (on API server) | Purpose |
|---|---|---|
| POST | /api/v1/autonomy/run | Full automation run (optional stream, budget_seconds) |
| POST | /api/v1/autonomy/vibe/run | Vibe coding run |
| GET | /api/v1/autonomy/streaming/{session_id}/events | SSE for a run session |
| GET | /api/v1/autonomy/smart-gates | Gate readiness snapshot |
| GET | /api/v1/autonomy/reliability-context | Budget / concurrency hints for the studio |
| GET | /api/v1/autonomy/evidence-pack | Evidence pack snapshot |
| POST | /api/v1/autonomy/voice/transcribe | Voice transcription |
Automation platform — sessions, automations, webhooks, workspace audit
The full multi-agent + integration surface. All routes are tenant-scoped via the standard request context. Webhook intake routes (/webhooks/...) sit OUTSIDE /api/v1 so external providers don't need to know our versioned layout.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/automations | List automations for the calling tenant. |
| POST | /api/v1/automations | Create a new automation from a template or definition. |
| POST | /api/v1/automations/run | Manually trigger an automation run. |
| GET | /api/v1/automations/{id}/status | Run status + metrics for an automation. |
| GET | /api/v1/automations/{id}/history | Recent runs with status, duration, summary. |
| PATCH | /api/v1/automations/{id} | Update name / description / triggers / tool allowlist / budget. |
| POST | /api/v1/automations/{id}/enable | Flip status to enabled. |
| POST | /api/v1/automations/{id}/disable | Flip status to disabled. |
| DELETE | /api/v1/automations/{id} | Archive (soft delete). |
| GET | /api/v1/automations/templates | List the 8 built-in customer-ready templates. |
| POST | /api/v1/automations/templates/instantiate | Create an automation from a template + variables. |
| GET | /api/v1/sessions | List multi-agent sessions (filter by status / kind). |
| POST | /api/v1/sessions | Create a new multi-agent session. |
| GET | /api/v1/sessions/{id} | Detail: session + agents + tasks + runs. |
| PATCH | /api/v1/sessions/{id} | Update title / goal / status. |
| DELETE | /api/v1/sessions/{id} | Archive session. |
| GET | /api/v1/sessions/{id}/agents | List agent definitions for a session. |
| POST | /api/v1/sessions/{id}/agents | Add an agent to a session. |
| GET | /api/v1/sessions/{id}/tasks | List session tasks (DAG order). |
| POST | /api/v1/sessions/{id}/tasks | Add a task; declare depends_on for DAG. |
| GET | /api/v1/sessions/{id}/runs | Recent runs for a session. |
| GET | /api/v1/sessions/{id}/messages | Inter-agent message log (durable). |
| POST | /api/v1/sessions/{id}/messages | Inject a user / system message into the session inbox. |
| GET | /api/v1/sessions/{id}/trace | SSE live stream — emits run / message / task events. |
| POST | /api/v1/autonomy/workspace-audit/run | Run unified security + architecture + sanity + health audit synchronously. |
| GET | /api/v1/autonomy/workspace-audit/stream | SSE — one phase_done event per audit phase. |
| GET | /api/v1/autonomy/workspace-audit/{report_id} | Re-fetch a recent audit report from the in-memory cache. |
| POST | /webhooks/{tenant_id}/github | GitHub webhook — X-Hub-Signature-256 verified, replay-window enforced. |
| POST | /webhooks/{tenant_id}/slack | Slack webhook — X-Slack-Signature + 5-min replay window; handles url_verification. |
| POST | /webhooks/{tenant_id}/linear | Linear webhook — Linear-Signature bare hex HMAC. |
| POST | /webhooks/{tenant_id}/pagerduty | PagerDuty webhook — v1=hex with comma-separated rotation tolerance. |
| POST | /webhooks/{tenant_id}/email | Inbound email parse (Mailgun multipart / Postmark JSON). |
| POST | /webhooks/{tenant_id}/generic | Generic JSON webhook with HMAC verification (X-Midcore-Signature). |
Workspace audit context
X-Midcore-Workspace-Root — when set (the web client adds it automatically in IDE-embed mode), the audit runs against the directory the user has open in the IDE rather than the server's default workspace. Sensitive paths (/etc, /proc,/sys) are refused unless MIDCORE_AUDIT_ALLOW_SENSITIVE_PATHS=1.Shorthand in UI copy
POST /autonomy/run as shorthand; the full server path is /api/v1/autonomy/run.Run vs vibe (security review)
RBAC, streaming, and audit behavior for /autonomy/run vs /autonomy/vibe/run are documented in your internal readiness and parity artifacts. Static HTML report bundles are not published on the public product site — see Readiness report (resources).
When to use the API
- Automating agent runs from scripts or CI/CD
- Integrating with external tools (ticketing, dashboards)
- Running gates and reading evidence from your own services
Authentication
API access uses cookies/session, API keys, or SSO depending on your deployment. Store secrets in environment variables or a secrets manager. See Authentication and Security.
Main use cases
- Triggering agent runs — Start a task remotely; use streaming endpoints for live output.
- Running gates — Same gate set as the CLI (
midcore gates run) with pass/fail and evidence. - Reading evidence — Query the evidence ledger and related autonomy snapshots.
App vs autonomy API · SDK and client libraries · CLI reference · Authentication