Control HTTP API

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

Route	Method	Purpose	Recommended SDK surface
`/v2/control/ingest`	`POST`	Async ingest for facts, traces, lessons, rules, WM, and other typed memory	`remember()` for normal writes, raw `client.control.ingest(...)` when you need job control
`/v2/control/batch_insert`	`POST`	Compatibility bulk write path	raw `client.control.batchInsert(...)` / `batch_insert(...)`
`/v2/control/ingest/jobs/:job_id`	`GET`	Ingest job status and completion	raw `client.control.getIngestJob(...)` / `get_ingest_job(...)`
`/v2/control/query`	`POST`	Answer-oriented routed retrieval	`recall()` or raw `client.control.query(...)`
`/v2/control/context`	`POST`	Pre-assembled context block with disclosure modes and budget control	`getContext()` / `get_context()`
`/v2/control/activity`	`POST`	Chronological memory/activity browse surface with scope and type filters	raw `client.control.listActivity(...)` when available, otherwise direct HTTP
`/v2/control/activity/export`	`POST`	Export chronological memory/activity as JSONL	direct HTTP or operator export tooling
`/v2/control/archive`	`POST`	Write an exact reusable artifact block and return a stable `reference_id`	`archive()` / `archive_block()`
`/v2/control/dereference`	`POST`	Fetch exact stored content by `reference_id`	`dereference()`
`/v2/control/diagnose`	`POST`	Failure-path lesson surfacing	`diagnose()`
`/v2/control/memory_health`	`POST`	Memory quality, staleness, contradictions, and section health	`memoryHealth()` / `memory_health()`
`/v2/control/reflect`	`POST`	Extract lessons and rules from run evidence	`reflect()`
`/v2/control/lessons`	`POST`	List stored lessons for a run/session scope	raw `client.control.lessons(...)`
`/v2/control/lessons/delete`	`POST`	Delete a stored lesson	`forget()` or raw lesson delete

MAS and learning-loop routes

Route	Method	Purpose	Recommended SDK surface
`/v2/control/agents`	`POST`	List registered agents for the run	`listAgents()` / `list_agents()`
`/v2/control/agents/register`	`POST`	Register an agent identity and its scopes	`registerAgent()` / `register_agent()`
`/v2/control/checkpoint`	`POST`	Save a pre-compaction or pre-transition checkpoint	`checkpoint()`
`/v2/control/outcome`	`POST`	Reinforce a lesson or rule after success/failure/partial outcome	`recordOutcome()` / `record_outcome()`
`/v2/control/step_outcome`	`POST`	Record a per-step process reward signal within a run	`recordStepOutcome()` / `record_step_outcome()`
`/v2/control/strategies`	`POST`	Surface repeated patterns from stored lessons and rules	`surfaceStrategies()` / `surface_strategies()`
`/v2/control/handoff`	`POST`	Persist a coordination handoff between agents	`handoff()`
`/v2/control/feedback`	`POST`	Persist a response to a handoff or review request	`feedback()`

Explicit planning and state routes

Route	Method	Purpose
`/v2/control/goals/add`	`POST`	Add a goal
`/v2/control/goals/update`	`POST`	Update a goal
`/v2/control/goals/list`	`POST`	List goals
`/v2/control/goals/tree`	`POST`	Retrieve the nested goal tree
`/v2/control/variables/set`	`POST`	Set an explicit run-scoped variable
`/v2/control/variables/get`	`POST`	Get a variable
`/v2/control/variables/list`	`POST`	List variables
`/v2/control/variables/delete`	`POST`	Delete a variable
`/v2/control/concepts/define`	`POST`	Define a concept
`/v2/control/concepts/list`	`POST`	List concepts
`/v2/control/actions/submit`	`POST`	Record an action
`/v2/control/actions/log`	`POST`	Read the action log
`/v2/control/cycles/run`	`POST`	Record a reasoning / planning cycle
`/v2/control/cycles/history`	`POST`	Read cycle history

Run management and agent lifecycle routes

Route	Method	Purpose	Recommended SDK surface
`/v2/control/runs`	`GET`	List recent runs	raw `client.control.listRuns(...)` / `list_runs(...)`
`/v2/control/runs/link`	`POST`	Link a child run to a parent run	raw `client.control.linkRun(...)` / `link_run(...)`
`/v2/control/runs/unlink`	`POST`	Unlink a previously linked run	raw `client.control.unlinkRun(...)` / `unlink_run(...)`
`/v2/control/delete_run`	`POST`	Delete a run and its associated data	raw `client.control.deleteRun(...)` / `delete_run(...)`
`/v2/control/agents/heartbeat`	`POST`	Agent liveness heartbeat signal	raw `client.control.agentHeartbeat(...)` / `agent_heartbeat(...)`
`/v2/control/activities/append`	`POST`	Append activity traces to a run	raw `client.control.appendActivity(...)` / `append_activity(...)`
`/v2/control/context/snapshot`	`POST`	Full context snapshot including working memory, attention, goals	raw `client.control.contextSnapshot(...)` / `get_run_snapshot(...)`
`/v2/control/events/subscribe`	`GET`	Stream control events via SSE	raw `client.control.subscribe(...)`
`/v2/control/ingest/stats`	`POST`	Get per-run ingest statistics	raw `client.control.getRunIngestStats(...)` / `get_run_ingest_stats(...)`

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:

Field	Type	Required	Description
`min_timestamp`	int64	no	Lower bound for temporal filter (unix seconds, inclusive). Filters by `occurrence_time` with `created_at` fallback.
`max_timestamp`	int64	no	Upper bound for temporal filter (unix seconds, inclusive).
`budget`	string	no	Search budget tier: `"low"`, `"mid"` (default), `"high"`. Controls latency/quality tradeoff.

Staleness fields in query evidence

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

Field	Type	Description
`is_stale`	bool	Whether this entry has been superseded by a newer version
`superseded_by`	string	ID of the superseding entry (empty if not stale)

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:

Field	Type	Required	Description
`occurrence_time`	int64	no	When the event actually occurred (unix seconds). Distinct from ingestion time. Used for temporal queries and recency ranking.

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

/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

Step-level outcome request shape

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

Field	Type	Required	Description
`run_id`	string	yes	Session/run identifier
`step_id`	string	yes	Unique step identifier within the run
`step_name`	string	no	Human-readable step label
`outcome`	string	yes	One of `success`, `failure`, `partial`, `neutral`
`signal`	float	no	Reward signal from -1.0 to 1.0
`rationale`	string	no	Why this outcome was assigned
`directive_hint`	string	no	Hindsight guidance for future runs
`agent_id`	string	no	Agent that performed the step
`user_id`	string	no	Logical user scope
`metadata_json`	string	no	Arbitrary JSON metadata

Response: { "step_outcome_id": "...", "accepted": true }. Use after each agentic step where you want dense reward signal. Then call reflect(include_step_outcomes=True) to produce step-attributed lessons.

Lane parameters

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

Route	Field	Description
`/v2/control/ingest`	`lane` (on each item)	Tags ingested items with a named lane
`/v2/control/query`	`lane_filter`	Retrieves only entries tagged with the specified lane
`/v2/control/context`	`lane_filter`	Filters context assembly by lane
`/v2/control/agents/register`	`shared_memory_lanes`	Declares which lanes an agent participates in

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

lane (MAS memory isolation) is distinct from the core data-plane retrieval lane concept used in direct search routing. See Core Direct Lanes for the data-plane concept.

Step-wise reflection parameters

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

Field	Type	Description
`step_id`	string	Scope reflection to a specific step
`last_n_items`	int32	Reflect only over the N most recent evidence items
`include_step_outcomes`	bool	Include recorded step outcomes as reflection input

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.

Field	Type	Required	Description
`run_id`	string	yes	Session/run identifier
`limit`	int32	no	Maximum entries to return (default 50)
`offset`	int32	no	Pagination offset
`entry_types`	string[]	no	Filter by entry type (e.g. `["fact", "lesson"]`)
`agent_id`	string	no	Filter by agent

Response: { "entries": [...], "total": int, "has_more": bool }.

`POST /v2/control/activity/export`

Export activity as JSONL.

Field	Type	Required	Description
`run_id`	string	yes	Session/run identifier
`format`	string	no	Export format, default `"jsonl"`
`entry_types`	string[]	no	Filter by entry type

Response: JSONL stream of activity entries.

`POST /v2/control/activities/append`

Append manual activity traces.

Field	Type	Required	Description
`run_id`	string	yes	Session/run identifier
`entries`	object[]	yes	Activity entries to append
`entries[].type`	string	yes	Entry type (e.g. `"observation"`, `"action"`)
`entries[].content`	string	yes	Entry content
`agent_id`	string	no	Agent that produced the entries

Response: { "appended": int }.

Run management request shapes

`POST /v2/control/runs/link`

Field	Type	Required	Description
`run_id`	string	yes	Parent run identifier
`linked_run_id`	string	yes	Child run to link

Response: { "linked": true }.

`POST /v2/control/runs/unlink`

Field	Type	Required	Description
`run_id`	string	yes	Parent run identifier
`linked_run_id`	string	yes	Child run to unlink

Response: { "unlinked": true }.

`POST /v2/control/delete_run`

Field	Type	Required	Description
`run_id`	string	yes	Run to delete

Response: { "deleted": true }.

`POST /v2/control/context/snapshot`

Field	Type	Required	Description
`run_id`	string	yes	Session/run identifier
`include_working_memory`	bool	no	Include working memory state
`include_goals`	bool	no	Include active goals

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

`POST /v2/control/ingest/stats`

Field	Type	Required	Description
`run_id`	string	yes	Session/run identifier

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

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

No request body. Returns:

Field	Type	Description
`job_id`	string	Job identifier
`status`	string	One of `pending`, `processing`, `completed`, `failed`
`items_total`	int	Total items in the job
`items_processed`	int	Items processed so far
`created_at`	string	ISO timestamp
`completed_at`	string	ISO timestamp (if completed)

Next steps

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

Control APIs

Core

Architecture

Control HTTP API

Core memory routes

MAS and learning-loop routes

Explicit planning and state routes

Run management and agent lifecycle routes

Operating guidance

Temporal query parameters

Staleness fields in query evidence

Occurrence time on ingest

Evidence provenance and context pressure

Step-level outcome request shape

Lane parameters

Step-wise reflection parameters

Activity routes request shapes

`POST /v2/control/activity`

`POST /v2/control/activity/export`

`POST /v2/control/activities/append`

Run management request shapes

`POST /v2/control/runs/link`

`POST /v2/control/runs/unlink`

`POST /v2/control/delete_run`

`POST /v2/control/context/snapshot`

`POST /v2/control/ingest/stats`

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

Next steps

Control APIs

Core

Architecture

​Core memory routes

​MAS and learning-loop routes

​Explicit planning and state routes

​Run management and agent lifecycle routes

​Operating guidance

​Temporal query parameters

​Staleness fields in query evidence

​Occurrence time on ingest

​Evidence provenance and context pressure

​Step-level outcome request shape

​Lane parameters

​Step-wise reflection parameters

​Activity routes request shapes

​POST /v2/control/activity

​POST /v2/control/activity/export

​POST /v2/control/activities/append

​Run management request shapes

​POST /v2/control/runs/link

​POST /v2/control/runs/unlink

​POST /v2/control/delete_run

​POST /v2/control/context/snapshot

​POST /v2/control/ingest/stats

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

​Next steps

Core memory routes

MAS and learning-loop routes

Explicit planning and state routes

Run management and agent lifecycle routes

Operating guidance

Temporal query parameters

Staleness fields in query evidence

Occurrence time on ingest

Evidence provenance and context pressure

Step-level outcome request shape

Lane parameters

Step-wise reflection parameters

Activity routes request shapes

`POST /v2/control/activity`

`POST /v2/control/activity/export`

`POST /v2/control/activities/append`

Run management request shapes

`POST /v2/control/runs/link`

`POST /v2/control/runs/unlink`

`POST /v2/control/delete_run`

`POST /v2/control/context/snapshot`

`POST /v2/control/ingest/stats`

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

Next steps