MirrorNeuron API
Reference for the FastAPI gateway over the MirrorNeuron runtime.
MirrorNeuron API
mn-api is the FastAPI gateway over the Python SDK and the MirrorNeuron gRPC runtime. The CLI, web UI, desktop clients, and automation clients use it for job, run, blueprint, model, service, schedule, resource, and cluster operations.
This is a reference page. Use Quickstart to learn the launch flow and the running service's OpenAPI schema for the precise versioned request and response shapes.
Before you integrate
- Start the runtime and verify it with
mn runtime health. - Keep the API listener on a trusted network.
- Use
MN_API_TOKENwhen API authentication is enabled. - Treat API launch endpoints as execution-capable operations; validate and review bundles before submitting them.
The default local base URL is:
http://localhost:54001/api/v1Set MN_API_PORT to change the port. In protected deployments, set MN_ENV=prod and configure MN_API_TOKEN; send it as a bearer token.
Discover the Current Schema
The running FastAPI service exposes its interactive OpenAPI documentation at:
http://localhost:54001/docsUse that schema as the authoritative request and response contract for the exact version you run.
Main Endpoints
| Method | Endpoint | Purpose |
|---|---|---|
GET | /health | API liveness and active configuration summary. |
GET | /runtime/status, /runtime/health, /runtime/doctor | Runtime status and diagnostics. |
GET | /system/summary, /nodes, /metrics | Cluster, node, and metrics summaries. |
GET, POST | /jobs | List or submit jobs. |
GET | /jobs/{job_id} | Read compact or full job detail. |
POST | /jobs/{job_id}/cancel, /pause, /resume | Control a job. |
GET | /jobs/{job_id}/events, /workflow-progress, /dead-letters | Inspect events, progress, and delivery failures. |
GET | /blueprints, /blueprints/{blueprint_id} | Discover catalog blueprints. |
POST | /blueprints/{blueprint_id}/install, /validate, /runs | Prepare, validate, or launch a catalog blueprint. |
GET | /runs/{run_id}/result, /artifacts, /logs, /timeline, /stream | Read run-store output and observability data. |
GET, POST | /models and /models/{model_id}/… | Inspect, install, validate, update, or remove local models. |
GET | /services, /services/{name}/resolve | Discover service instances. |
GET, POST, PUT | /resource | Read or set coarse resource limits. |
GET, POST, PATCH, DELETE | /schedules and /schedules/{schedule_id} | Manage cron, delayed, and event schedules. |
POST, GET | /events | Emit or list runtime trigger events. |
POST | /system/cluster/nodes:add, /nodes:join, /nodes:remove, /nodes:leave | Manage cluster membership. |
Examples
Health check:
curl -s http://localhost:54001/api/v1/healthList jobs, including terminal jobs:
curl -s "http://localhost:54001/api/v1/jobs?limit=5&include_terminal=true"List configured catalog blueprints:
curl -s http://localhost:54001/api/v1/blueprintsFor normal local execution, prefer the CLI because it packages local blueprint folders and presents runtime output:
mn blueprint run --folder otterdesk-blueprints/<blueprint_folder>Replace <blueprint_folder> with a validated local blueprint folder. Verify a launch by querying the returned job ID through GET /jobs/{job_id} or by running mn job status <job_id>.
Authentication and Security
Do not expose the API publicly without an authentication boundary. With API authentication enabled, add:
Authorization: Bearer <MN_API_TOKEN>The API controls execution-capable runtime operations. Validate and review third-party bundles before launch, and keep the API listener on a trusted network. See Security Model.