The Runs API orchestrates multi-agent workflows through the WattSwarm run queue. A run groups multiple agent steps (each backed by an executor) that all operate on the same shared inputs. Once a run finishes, the kernel aggregates the individual results — resolving ties and null outputs according to the configured policy — and produces a single final_decision. Runs are the recommended way to leverage multiple independent agents for higher-confidence swarm decisions.
POST /api/run/submit Submits a RunSubmitSpec and registers the run in the queue. By default the run starts in CREATED state; pass "kickoff": true in the envelope form to also transition all steps to QUEUED immediately.
The endpoint accepts the spec either as a bare RunSubmitSpec object or wrapped in an envelope:
{ "kickoff" : true , "spec" : { ... } }
Stable identifier for this run. Use a UUID or a deterministic slug.
Task type string passed to each executor step. Defaults to "generic.v1".
JSON inputs shared across all agent steps in the run.
List of agent step specifications. Unique identifier for this agent within the run.
Name of the registered executor that will handle this step.
Executor profile to use. Defaults to "default".
Prompt or instruction string sent to the executor for this step.
Relative weight for confidence-weighted aggregation. Defaults to 1.0.
Step scheduling priority. Higher values are dequeued first. Defaults to 0.
Retry policy applied to failed steps. Maximum execution attempts per step. Defaults to 2.
Milliseconds to wait between retry attempts. Defaults to 1500.
Controls how individual step results are combined into a final decision. Aggregation trigger: "all_done" (default) — finalize once all steps complete.
Minimum number of agreeing results required for a positive decision.
Complete RunSubmitSpec example: { "run_id" : "run-2024-demo-001" , "task_type" : "generic.qa.v1" , "shared_inputs" : { "question" : "What is the capital of France?" }, "agents" : [ { "agent_id" : "agent-alpha" , "executor" : "local-agent" , "profile" : "default" , "prompt" : "Answer the question concisely with high confidence." , "weight" : 1.0 , "priority" : 0 }, { "agent_id" : "agent-beta" , "executor" : "local-agent" , "profile" : "detailed" , "prompt" : "Answer the question with supporting evidence." , "weight" : 1.5 , "priority" : 0 } ], "retry" : { "max_attempts" : 2 , "backoff_ms" : 1500 }, "aggregation" : { "mode" : "all_done" , "quorum" : 2 } }
Example request: curl -X POST http://127.0.0.1:7788/api/run/submit \ -H "Content-Type: application/json" \ -d '{ "kickoff": true, "spec": { "run_id": "run-2024-demo-001", "task_type": "generic.qa.v1", "shared_inputs": { "question": "What is the capital of France?" }, "agents": [ { "agent_id": "agent-alpha", "executor": "local-agent", "profile": "default", "prompt": "Answer concisely." } ] } }'
Example response: { "ok" : true , "run_id" : "run-2024-demo-001" }
POST /api/run/kickoff/:run_id Transitions the run and all its constituent steps from CREATED to QUEUED, making them eligible for executor pickup. Call this after /api/run/submit if you did not pass "kickoff": true at submit time, or if you want to delay execution start.
POST /api/run/kickoff/:run_id
Path parameters: The run identifier returned by /api/run/submit.
Example request: curl -X POST http://127.0.0.1:7788/api/run/kickoff/run-2024-demo-001
Example response: { "ok" : true , "run_id" : "run-2024-demo-001" }
GET /api/run/watch/:run_id Polls the current status of a run, including step-level counts broken down by state. Call this endpoint periodically until status reaches SUCCEEDED, FAILED, or CANCELLED.
GET /api/run/watch/:run_id
Path parameters: Example request: curl http://127.0.0.1:7788/api/run/watch/run-2024-demo-001
Example response: { "ok" : true , "watch" : { "run_id" : "run-2024-demo-001" , "status" : "LEASED" , "task_type" : "generic.qa.v1" , "created_at" : 1718000000000 , "updated_at" : 1718000005000 , "started_at" : 1718000001000 , "finished_at" : null , "counts" : { "created" : 0 , "queued" : 0 , "leased" : 1 , "succeeded" : 1 , "failed" : 0 , "retry_wait" : 0 , "cancelled" : 0 , "remote_dispatched" : 0 } } }
Response fields: Overall run status: CREATED, QUEUED, LEASED, SUCCEEDED, FAILED, or CANCELLED.
Step-level counts by state. remote_dispatched tracks steps sent to remote nodes awaiting gossip results.
GET /api/run/result/:run_id Returns the aggregated final result of a completed run, including the final decision, final answer, and per-step conclusions.
GET /api/run/result/:run_id
Path parameters: Example request: curl http://127.0.0.1:7788/api/run/result/run-2024-demo-001
Example response: { "ok" : true , "result" : { "run_id" : "run-2024-demo-001" , "status" : "SUCCEEDED" , "final_decision" : "Paris" , "final_answer" : "Paris is the capital of France." , "steps" : [ { "step_id" : "step-agent-alpha-001" , "agent_id" : "agent-alpha" , "status" : "SUCCEEDED" , "conclusion" : "Paris" , "confidence" : 0.98 , "attempt" : 1 }, { "step_id" : "step-agent-beta-001" , "agent_id" : "agent-beta" , "status" : "SUCCEEDED" , "conclusion" : "Paris" , "confidence" : 0.97 , "attempt" : 1 } ], "aggregation" : { "resolution_paths" : [ "quorum_match" ] } } }
The aggregated decision value. null if the run did not produce a conclusive result.
The long-form answer string, if the executor returned one.
Per-step outcome details including conclusion, confidence, and attempt number.
result.aggregation.resolution_paths
List of resolution strategies that were applied (e.g. "quorum_match", "confidence_weighted", "stochastic").
GET /api/run/events/:run_id Returns the structured event log for a run. Useful for debugging step transitions, retries, and aggregation decisions.
GET /api/run/events/:run_id?limit= 50
Path parameters: Query parameters: Maximum number of events to return. Defaults to 50; minimum 1.
Example request: curl "http://127.0.0.1:7788/api/run/events/run-2024-demo-001?limit=20"
Example response: { "ok" : true , "events" : [ { "id" : 1 , "run_id" : "run-2024-demo-001" , "event_type" : "run_created" , "payload" : {}, "created_at" : 1718000000000 }, { "id" : 2 , "run_id" : "run-2024-demo-001" , "event_type" : "step_queued" , "payload" : { "step_id" : "step-agent-alpha-001" , "agent_id" : "agent-alpha" }, "created_at" : 1718000001000 } ] }
POST /api/run/cancel/:run_id Cancels an active run. Any steps in QUEUED or CREATED state are moved to CANCELLED. Steps currently leased are allowed to finish but their results are discarded.
POST /api/run/cancel/:run_id
Path parameters: Example request: curl -X POST http://127.0.0.1:7788/api/run/cancel/run-2024-demo-001
Example response: { "ok" : true , "run_id" : "run-2024-demo-001" }
POST /api/run/retry/:run_id Retries a failed run by re-queuing its failed steps from the beginning. Steps that already succeeded are not re-executed.
POST /api/run/retry/:run_id
Path parameters: Example request: curl -X POST http://127.0.0.1:7788/api/run/retry/run-2024-demo-001
Example response: { "ok" : true , "run_id" : "run-2024-demo-001" }
POST /api/knowledge/export Exports a knowledge bundle from the kernel store. A knowledge bundle contains the decision records, evidence references, and reuse metrics accumulated for a given task type or specific task ID. Provide exactly one of task_type or task_id.
POST /api/knowledge/export
Export all knowledge records associated with this task type string (e.g. "generic.qa.v1"). Mutually exclusive with task_id.
Export knowledge records for a single specific task. Mutually exclusive with task_type.
Example request: curl -X POST http://127.0.0.1:7788/api/knowledge/export \ -H "Content-Type: application/json" \ -d '{ "task_type": "generic.qa.v1" }'
Example response: { "ok" : true , "knowledge" : { "task_type" : "generic.qa.v1" , "records" : [ { "task_id" : "task-demo-001" , "finalized_at" : 1718000010000 , "decision_value" : "Paris" , "confidence" : 0.98 , "evidence_count" : 2 , "reuse_attempts" : 0 , "reuse_successes" : 0 } ] } }
Knowledge bundles are useful for fine-tuning prompts, auditing swarm consensus quality, and bootstrapping new nodes with historical decision context.