HTTP API

Connect and authenticate

The default base URL is http://localhost:54001/api/v1. Start the runtime first. From a terminal on that host:

curl --fail-with-body -sS http://localhost:54001/api/v1/health

Verify api_contract is mirrorneuron.rest.v1. The health endpoint is unauthenticated. When MN_API_TOKEN is configured, every other request requires Authorization: Bearer <token>. The examples below include that header; substitute your token and keep it out of source control and shared terminal logs.

Upload a package and create a job

Run from the directory containing a reviewed worker-bundle.zip. Uploading stages the package; creating a job can prepare its declared resources. Review code and external actions first.

curl --fail-with-body -sS -X POST http://localhost:54001/api/v1/bundles \
  -H "Authorization: Bearer <token>" \
  -F "bundle=@./worker-bundle.zip"

Use the returned bundle_id to create the durable definition. Replace <uuid> with a fresh request identifier:

curl --fail-with-body -i -X POST http://localhost:54001/api/v1/jobs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{"bundle_id":"<bundle-id>"}'

A catalog job can use blueprint_id instead of bundle_id. Keep the returned public job_id and ETag. Job configuration is supplied as resolved_configuration when creating or updating a definition.

Start and inspect a run

Use a new idempotency key for each intended execution:

curl --fail-with-body -i -X POST http://localhost:54001/api/v1/jobs/<job-id>/runs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{"inputs":{}}'

A 202 Accepted response means execution was accepted, not completed. Use the returned public run_id:

curl --fail-with-body -sS http://localhost:54001/api/v1/runs/<run-id> \
  -H "Authorization: Bearer <token>"

Catalog-backed jobs also accept config_overrides at run creation. These overrides reprepare the job definition; inputs is workflow input, not blueprint configuration. Internal runtime_run_id values must not appear in client URLs.

Pause, resume, or cancel

curl --fail-with-body -sS -X PATCH http://localhost:54001/api/v1/runs/<run-id> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"desired_state":"paused"}'

Use running to resume and cancelled to cancel. Invalid transitions return 409. Cancellation cannot reverse external actions already performed.

Follow progress and retrieve outputs

curl -N http://localhost:54001/api/v1/runs/<run-id>/events/stream \
  -H "Authorization: Bearer <token>"

Persist each applied event ID and reconnect with Last-Event-ID. Use ordinary Run GETs and event history to recover state. Streams close after terminal events. Run artifact and output lists are available at /runs/<run-id>/artifacts and /runs/<run-id>/outputs; follow returned download URLs. Review warnings and outputs before treating a completed execution as a correct result.

Collections and concurrent updates

Collections return items and next_page_token. Request page_size (default 50, maximum 200), then pass the returned opaque page_token unchanged. Tokens expire after 24 hours and are bound to the original query and principal.

Send Idempotency-Key for non-idempotent POSTs. Replay records last 24 hours; a reused key with a different request returns 409. Persistent job, schedule, deployment, model registration, and model installation updates/deletions require the current ETag in If-Match. Missing conditions return 428; stale conditions return 412.

Errors use application/problem+json, including code, detail, and request_id. Unknown request fields are rejected.

Prepare a catalog blueprint

POST /blueprints/<blueprint-id>/additions with { "force": false } starts preparation and returns an Operation. Poll the returned Location or use /operations/<operation-id>/events/stream until completed or failed. Display supplied progress labels and inspect the terminal error before retrying with a new idempotency key.

Removal can delete blueprint-owned resources. Preview with POST /blueprints/<blueprint-id>/removals and { "dry_run": true }. To retain resources, submit { "keep_resources": true, "keep_models": true } with a new key. Re-adding cannot recover deleted data.

Query a job through MCP

A package with the mn.response extension enabled exposes a job-scoped Streamable HTTP endpoint at /jobs/<job-id>/mcp. Configure your MCP client with that URL and the same bearer credential. Tools include get_job_profile, get_latest_run, get_job_context, and ask_job. The last answers questions from bounded job evidence without starting a run. Legacy collaboration-enabled jobs expose the first three tools only.

Use this interface for purpose, status, and published evidence. It is not a general log/artifact download or job-control interface.

Route compatibility and cleanup

/api/v2, /runtime-runs, WebSocket routes, and blueprint installation aliases are removed. Use canonical /api/v1 resources and SSE.

Preserve outputs and diagnostic evidence before deleting runs or jobs. For a local CLI cleanup procedure, see Monitor. Refer to CLI reference when operating the same resources from a terminal.