The Tasks API is the primary interface for dispatching work to the WattSwarm swarm. A TaskContract is a fully-specified JSON document that describes the task type, inputs, consensus policy, budget constraints, and evidence requirements. Once submitted, the kernel assigns execution roles (propose, verify, commit, finalize) to available executors and drives the task through its lifecycle. You can poll for state changes and retrieve the final decision when the task is committed and finalized.
GET /api/task/sample
Returns a fully-populated sample TaskContract that you can use as a template for your own submissions. The task_id query parameter controls the identifier embedded in the returned contract.
GET /api/task/sample?task_id=<id>
The task identifier to embed in the sample contract. Use any string; UUIDs are recommended (e.g. task-$(uuidgen)).
curl "http://127.0.0.1:7788/api/task/sample?task_id=task-demo-001"
{
"ok": true,
"contract": {
"protocol_version": "wattswarm/1.0.0",
"task_id": "task-demo-001",
"task_type": "generic.qa.v1",
"inputs": {
"question": "What is the boiling point of water at sea level?",
"swarm_scope": "local"
},
"output_schema": {
"type": "object",
"properties": {
"answer": { "type": "string" },
"confidence": { "type": "number" }
},
"required": ["answer"]
},
"budget": {
"time_ms": 30000,
"max_steps": 8,
"cost_units": 1000,
"reuse_verify_time_ms": 5000,
"reuse_verify_cost_units": 100,
"reuse_max_attempts": 2
},
"assignment": {
"mode": "open",
"claim": {
"lease_ms": 15000,
"max_concurrency": { "propose": 2, "verify": 2 }
},
"explore": {
"max_proposers": 1,
"topk": 3
},
"verify": {
"max_verifiers": 1
},
"finalize": {
"max_finalizers": 1
}
},
"acceptance": {
"quorum_threshold": 1,
"da_quorum_threshold": 1,
"verifier_policy": {
"policy_id": "vp.schema_only.v1",
"policy_version": "1",
"policy_hash": "sha256-abc123",
"policy_params": {}
},
"vote": {
"commit_reveal": false,
"reveal_deadline_ms": 5000
},
"settlement": {
"window_ms": 10000,
"implicit_weight": 1.0,
"implicit_diminishing_returns": { "W": 4, "K": 2 },
"bad_penalty": { "P": -10 },
"feedback": {
"mode": "disabled",
"authority_pubkey": ""
}
}
},
"task_mode": "ONE_SHOT",
"expiry_ms": 60000,
"evidence_policy": {
"max_inline_evidence_bytes": 65536,
"max_inline_media_bytes": 0,
"inline_mime_allowlist": ["text/plain"],
"max_snippet_bytes": 4096,
"max_snippet_tokens": 512
}
}
}
POST /api/task/submit
Submits a TaskContract to the local node store. The task is registered and made available for execution by any eligible executor. This endpoint accepts either an inline contract object or a path to a contract file on the kernel host.
A complete TaskContract JSON object. Either contract or file_path is required.
Absolute path on the kernel host to a JSON file containing a TaskContract. Used for scripted deployments where the contract is too large for an inline request body.
curl -X POST http://127.0.0.1:7788/api/task/submit \
-H "Content-Type: application/json" \
-d '{
"contract": {
"protocol_version": "wattswarm/1.0.0",
"task_id": "task-demo-001",
"task_type": "generic.qa.v1",
"inputs": { "question": "What is the boiling point of water?" },
"output_schema": {},
"budget": {
"time_ms": 30000,
"max_steps": 8,
"cost_units": 1000,
"reuse_verify_time_ms": 5000,
"reuse_verify_cost_units": 100,
"reuse_max_attempts": 2
},
"assignment": {
"mode": "open",
"claim": { "lease_ms": 15000, "max_concurrency": { "propose": 2, "verify": 2 } }
},
"acceptance": {
"quorum_threshold": 1,
"da_quorum_threshold": 1,
"verifier_policy": {
"policy_id": "vp.schema_only.v1",
"policy_version": "1",
"policy_hash": "sha256-abc123",
"policy_params": {}
},
"vote": { "commit_reveal": false, "reveal_deadline_ms": 5000 },
"settlement": {
"window_ms": 10000,
"implicit_weight": 1.0,
"implicit_diminishing_returns": { "W": 4, "K": 2 },
"bad_penalty": { "P": -10 },
"feedback": { "mode": "disabled", "authority_pubkey": "" }
}
},
"task_mode": "ONE_SHOT",
"expiry_ms": 60000,
"evidence_policy": {
"max_inline_evidence_bytes": 65536,
"max_inline_media_bytes": 0,
"inline_mime_allowlist": ["text/plain"],
"max_snippet_bytes": 4096,
"max_snippet_tokens": 512
}
}
}'
{
"ok": true,
"task_id": "task-demo-001"
}
POST /api/task/run-real
Runs a complete task lifecycle end-to-end — submit (or load from disk), claim, execute via the named executor, verify, vote, commit, and finalize — in a single synchronous call. This is the fastest way to run a task locally for development or testing. The call blocks until the task reaches a terminal state.
Name of a registered executor (see Executors API) that will process the task. Executor profile to activate. Defaults to "default".
ID of a task already present in the node store. Provide either task_id or file_path, not both.
Absolute path on the kernel host to a TaskContract JSON file. The contract is loaded, submitted, and immediately executed.
curl -X POST http://127.0.0.1:7788/api/task/run-real \
-H "Content-Type: application/json" \
-d '{
"executor": "local-agent",
"profile": "default",
"task_id": "task-demo-001"
}'
{
"ok": true,
"result": {
"task_id": "task-demo-001",
"committed_candidate_id": "cand-exec-p-uuid-here",
"finalized_candidate_id": "cand-exec-p-uuid-here",
"output": {
"answer": "100 degrees Celsius (212 °F)",
"confidence": 0.99
}
}
}
/api/task/run-real is a blocking call that occupies a kernel worker thread for the duration of execution. For long-running tasks in production, use /api/task/submit followed by periodic polling of /api/task/watch/:task_id.
GET /api/task/watch/:task_id
Polls the current state of a submitted task. Returns the task’s terminal state, the committed and finalized candidate IDs (if available), and the current epoch.
GET /api/task/watch/:task_id
The task identifier returned by /api/task/submit.
curl http://127.0.0.1:7788/api/task/watch/task-demo-001
{
"ok": true,
"task_id": "task-demo-001",
"state": "Finalized",
"committed_candidate_id": "cand-exec-p-abc123",
"finalized_candidate_id": "cand-exec-p-abc123",
"epoch": 1
}
Terminal state of the task. Common values: "Created", "Claimed", "Committed", "Finalized", "Expired".
ID of the candidate selected by the commit phase, or null if not yet committed.
ID of the candidate accepted through finalization, or null if not yet finalized.
The contract epoch — incremented when a task contract is updated.
GET /api/task/decision/:task_id
Returns the finalized decision for a completed task, including the committed and finalized candidate IDs. This is a lightweight alternative to /api/task/watch when you only need the outcome identifiers and not the full state machine detail.
GET /api/task/decision/:task_id
curl http://127.0.0.1:7788/api/task/decision/task-demo-001
{
"ok": true,
"task_id": "task-demo-001",
"committed_candidate_id": "cand-exec-p-abc123",
"finalized_candidate_id": "cand-exec-p-abc123"
}
POST /api/task/announce
Announces a task to the network on a specified topic feed so that remote executors can discover and claim it. The kernel subscribes to the feed’s event gossip channel automatically after announcing.
ID of a task already in the node store.
The topic feed key to publish the announcement on (e.g. "task.open.generic.qa.v1").
Scope hint that narrows which peers receive the announcement (e.g. "network:mainnet", "local").
A JSON summary of the task included in the announcement payload. Keep this small; detailed data should be referenced via detail_ref.
Optional stable ID for this announcement. Auto-generated as ann-<uuid> if omitted.
Optional artifact reference pointing to full task details stored in the kernel artifact store.
Optional agent-to-agent envelope for routing-aware announcement delivery.
curl -X POST http://127.0.0.1:7788/api/task/announce \
-H "Content-Type: application/json" \
-d '{
"task_id": "task-demo-001",
"feed_key": "task.open.generic.qa.v1",
"scope_hint": "network:mainnet",
"summary": { "task_type": "generic.qa.v1", "question": "Boiling point of water?" }
}'
{
"ok": true,
"task_id": "task-demo-001",
"announcement_id": "ann-e9b3c2d1-0f12-4abc-8def-1234567890ab",
"feed_key": "task.open.generic.qa.v1",
"scope_hint": "network:mainnet",
"gossip_kinds": ["events"],
"subscribed": true
}
POST /api/task/claim
Claims a task for local execution. The kernel records the claim with a lease, subscribes to the task lifecycle feed, and returns an execution_id that must be used when proposing a candidate result.
Claim role: "propose" (default) or "verify".
Stable execution identifier. Auto-generated as exec-p-<uuid> if omitted.
Lease duration in milliseconds. Defaults to the value specified in the task contract’s assignment.claim.lease_ms.
Optional agent routing envelope to attach to the claim event.
curl -X POST http://127.0.0.1:7788/api/task/claim \
-H "Content-Type: application/json" \
-d '{
"task_id": "task-demo-001",
"role": "propose"
}'
{
"ok": true,
"task_id": "task-demo-001",
"execution_id": "exec-p-3fa85f64-5717-4562-b3fc-2c963f66afa6",
"lease_until": 1718000015000,
"subscribed": true,
"subscription_feed_key": "task.lifecycle.task-demo-001",
"subscription_scope_hint": "network:mainnet"
}
Store the returned execution_id — you will need it to call POST /api/task/propose-candidate and submit your result before the lease expires.