Control HTTP API

Current public Mubit control-plane HTTP routes for memory, context, diagnostics, coordination, and explicit planning state.

This page documents the current public HTTP control surface. In application code, prefer the helper-first SDK methods where they exist and use these routes as wire-contract and debugging references.

Core memory routes

MAS and learning-loop routes

Explicit planning and state routes

Run management and agent lifecycle routes

Operating guidance

• Prefer the Client namespaces (and the global helpers inside a run) for normal application code.
• Use client.raw.invoke(op, payload) when you need exact request-shape control, ingest-job polling, or contract debugging; op is the contract name (control.<route>).
• Treat /v2/control/context as the default compaction-safe context assembly surface for long-running systems.
• Treat /v2/control/activity as the chronological audit surface for stored Mubit data. It is separate from semantic query.
• Use /v2/control/archive plus /v2/control/dereference when later steps need exact artifact fidelity rather than only semantic discovery.
• Use client.memory.diagnose, client.memory.health, and client.lessons.strategies before changing prompts blindly.

Temporal query parameters

POST /v2/control/query and POST /v2/control/context accept temporal filtering and budget control:

Staleness fields in query evidence

Evidence items in query and context responses may include staleness metadata:

Stale entries are returned with a ranking penalty. Filter them in your application if you only want current information.

Occurrence time on ingest

POST /v2/control/ingest items accept an occurrence time field:

Evidence provenance and context pressure

/v2/control/query and /v2/control/context now expose reuse provenance on surfaced evidence:

• retrieval_mode: semantic, exact_reference, checkpoint, rule_overlay, lesson_overlay, or working_memory
• reference_id: stable exact-reference ID when available
• referenceable: whether the source can be dereferenced later
• origin_entry_type: typed LTM source such as fact, lesson, rule, archive_block, or checkpoint

The /v2/control/query response also includes a citations array — 0-based indices into evidence marking which items grounded final_answer (empty when the answer cites no specific evidence or was an abstention). Indices are validated server-side against the evidence length, so every value is a valid index into evidence. Use them to render citations or audit answer grounding.

/v2/control/context also reports context-pressure telemetry:

• requested token budget
• budget_used
• budget_remaining
• source counts by entry type
• source counts by retrieval mode
• evidence_candidates_considered
• evidence_dropped_by_budget
• exact_references_surfaced

Run-level outcome request shape

POST /v2/control/outcome reinforces a lesson or rule after a success/failure/partial outcome. Beyond the core fields (reference_id, outcome, signal, rationale, agent_id, user_id, verified_in_production), the wire request accepts two attribution fields:

Step-level outcome request shape

POST /v2/control/step_outcome records a per-step process reward signal, complementing the run-level /v2/control/outcome.

Response: { "step_outcome_id": "...", "accepted": true }.

Use after each agentic step where you want dense reward signal. To produce step-attributed lessons, set include_step_outcomes on the reflect request. This is a wire-level ReflectRequest field (not a kwarg on client.lessons.reflect()): send it through the raw operation, e.g. client.raw.invoke("control.reflect", {"run_id": ..., "include_step_outcomes": True}) (Python) or client.raw.invoke("control.reflect", { run_id, include_step_outcomes: true }) (JS).

Lane parameters

Lanes partition memory within a shared run for multi-agent isolation.

Items without a lane are visible to all queries. Items with a lane are visible only when lane_filter matches or is empty.

Step-wise reflection parameters

POST /v2/control/reflect now accepts additional fields for targeted reflection:

These compose with existing fields (run_id, checkpoint_id). Use last_n_items for incremental after-each-step reflection, and include_step_outcomes when step reward signals should influence lesson extraction. Use lessons when your own agent already extracted the lessons and you want them gated, stored and promoted exactly as reflected ones are — the response decisions are the same, and stored rows carry auto_extracted: false.

Activity routes request shapes

POST /v2/control/activity

List chronological memory/activity entries.

Response: { "entries": [...], "next_page_token": "...", "total_visible": int }. next_page_token is empty when the last page has been reached.

POST /v2/control/activity/export

Export activity as JSONL. The request takes the same filter fields as the browse call — there is no format request field; the response is always JSONL.

Response: { "format": "jsonl", "content": "<serialized entries>", "entry_count": int }.

POST /v2/control/activities/append

Append a manual activity trace. Each request appends a single activity record — issue one request per record.

Response: { "success": true, "event_id": "evt_..." }.

Run management request shapes

POST /v2/control/runs/link

Response: { "linked": true }.

POST /v2/control/runs/unlink

Response: { "unlinked": true }.

POST /v2/control/delete_run

Response: { "deleted": true }.

POST /v2/control/context/snapshot

Response: { "snapshot": { "working_memory": {...}, "attention": {...}, "goals": [...] } }.

POST /v2/control/ingest/stats

Response: { "total_ingested": int, "by_type": {...}, "last_ingest_at": string }.

GET /v2/control/ingest/jobs/:job_id

No request body. Returns:

Managed resources: Projects, Agents, Skills, Prompts

Managed Mubit deployments expose a resource model so you can configure agents declaratively instead of re-encoding them in every run. Projects group related agents, each agent owns a versioned system prompt and a set of skills (tools/playbooks), and all of it is versioned with a candidate → active promotion flow.

Project CRUD

POST /v2/control/projects request:

Response: { "project": { "project_id": "proj-...", "name": "...", "description": "...", "agent_ids": [], "created_at": "...", "updated_at": "..." } }.

Agent Definition CRUD

Agents belong to a project and own a role, description, and active system prompt.

POST /v2/control/projects/agents request:

Run history for a project

Run history records expose lessons_extracted, prompt_changes, avg_outcome_score, outcome_count, and ingest_count per run — so you can observe how an agent's behavior evolves.

Prompt versioning + optimization

Every agent has at most one active PromptVersion and zero or more candidate PromptVersions awaiting approval. The control plane can mint candidates automatically via optimize_prompt.

Version statuses: active, candidate, retired, archived. Sources: manual, optimization, rollback.

POST /v2/control/prompt/optimize request:

Response: { success, candidate, optimization_summary, confidence, activated }.

Skill CRUD + optimization

Skills are named tools or playbooks attached to a project (or optionally to a specific agent). They version identically to prompts.

POST /v2/control/skills request:

Control sessions

Sessions are long-lived handles the control plane uses to coordinate multi-turn agent work. In typical SDK usage, run_id serves the same purpose; sessions are exposed for tools that need explicit lifecycle control.

Platform health endpoints

These unauthenticated routes live at the root of each Mubit node (alongside /v2/core/* and /v2/control/*). Use them for Kubernetes probes, load-balancer checks, and operational monitoring — not from application code.

GET /livez

Response: 200 OK with body ok.

Liveness is intentionally cheap. It does not query storage, Redis, or any downstream dependency — that is the job of /readyz. A failing /livez means the process is wedged and should be restarted.

GET /readyz

• Ready: 200 OK

  { "status": "ready" }

• Not ready: 503 Service Unavailable

  { "status": "not_ready", "reason": "acl_rebuild_in_progress" }

The node flips to ready once the initial ACL warmup, sparse-index prewarm, and partitioned sparse prewarm complete. During that window, the process accepts connections (so /livez stays 200) but returns 503 from /readyz so the load balancer can route around it.

Typical reason values: starting, acl_rebuild_in_progress, sparse_prewarm_in_progress. Treat reason as a diagnostic hint — it is advisory, not API-stable.

Next steps

• Compare the proto surface at Control gRPC reference.
• Review explicit planning routes at State management endpoints.