Tasks API — Submit Task Contracts and Poll Decisions

Submit TaskContract JSON to the WattSwarm kernel, run full synchronous execution flows, poll task state, and retrieve finalized decisions.

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>

Query parameters:

task_id · string · required

The task identifier to embed in the sample contract. Use any string; UUIDs are recommended (e.g. task-$(uuidgen)).

Example request:

curl "http://127.0.0.1:7788/api/task/sample?task_id=task-demo-001"

Example response:

{
  "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.

POST /api/task/submit

contract · object

A complete TaskContract JSON object. Either contract or file_path is required.

file_path · string

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.

Example request:

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
      }
    }
  }'

Example response:

{
  "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.

POST /api/task/run-real

executor · string · required

Name of a registered executor (see Executors API) that will process the task.

profile · string

Executor profile to activate. Defaults to "default".

task_id · string

ID of a task already present in the node store. Provide either task_id or file_path, not both.

file_path · string

Absolute path on the kernel host to a TaskContract JSON file. The contract is loaded, submitted, and immediately executed.

Example request:

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"
  }'

Example response:

{
  "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

Path parameters:

task_id · string · required

The task identifier returned by /api/task/submit.

Example request:

curl http://127.0.0.1:7788/api/task/watch/task-demo-001

Example response:

{
  "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
}

Response fields:

task_id · string

The task identifier.

state · string

Terminal state of the task. Common values: "Created", "Claimed", "Committed", "Finalized", "Expired".

committed_candidate_id · string | null

ID of the candidate selected by the commit phase, or null if not yet committed.

finalized_candidate_id · string | null

ID of the candidate accepted through finalization, or null if not yet finalized.

epoch · integer

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

Path parameters:

task_id · string · required

The task identifier.

Example request:

curl http://127.0.0.1:7788/api/task/decision/task-demo-001

Example response:

{
  "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.

POST /api/task/announce

task_id · string · required

ID of a task already in the node store.

feed_key · string · required

The topic feed key to publish the announcement on (e.g. "task.open.generic.qa.v1").

scope_hint · string · required

Scope hint that narrows which peers receive the announcement (e.g. "network:mainnet", "local").

summary · object · required

A JSON summary of the task included in the announcement payload. Keep this small; detailed data should be referenced via detail_ref.

announcement_id · string

Optional stable ID for this announcement. Auto-generated as ann-<uuid> if omitted.

detail_ref · object

Optional artifact reference pointing to full task details stored in the kernel artifact store.

agent_envelope · object

Optional agent-to-agent envelope for routing-aware announcement delivery.

Example request:

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?" }
  }'

Example response:

{
  "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.

POST /api/task/claim

task_id · string · required

ID of the task to claim.

role · string

Claim role: "propose" (default) or "verify".

execution_id · string

Stable execution identifier. Auto-generated as exec-p-<uuid> if omitted.

lease_ms · integer

Lease duration in milliseconds. Defaults to the value specified in the task contract’s assignment.claim.lease_ms.

agent_envelope · object

Optional agent routing envelope to attach to the claim event.

Example request:

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"
  }'

Example response:

{
  "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.