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 helper methods for normal application code.
• Use raw route-level control when you need exact request-shape control, ingest-job polling, or contract debugging.
• 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 diagnose, memory_health, and 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 the Python reflect() helper): send it via the raw control surface, e.g. client.advanced.reflect({"run_id": ..., "include_step_outcomes": True}) (Python) or client.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.

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.

Response: JSONL stream of activity entries.

POST /v2/control/activities/append

Append manual activity traces.

Response: { "appended": int }.

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.