WattSwarm Kernel HTTP API — Complete Reference Overview

Complete reference for the WattSwarm kernel HTTP API — all endpoint groups, JSON response format conventions, and links to each API reference page.

The WattSwarm kernel exposes a local HTTP API that lets you control the node lifecycle, submit tasks, manage executors, exchange messages with peers, and inspect diagnostics — all over a plain JSON interface. By default the server binds on http://127.0.0.1:7788; you can override this with the --listen flag when starting the kernel.

Base URL

http://<host>:7788

The address is configurable at startup:

wattswarm --listen 0.0.0.0:7788

For local development no authentication is required. In production, place the kernel behind a reverse proxy (nginx, Caddy, etc.) or enforce network-level access controls before exposing port 7788 to untrusted clients.

Response Format

Every endpoint returns Content-Type: application/json. Successful responses always include "ok": true alongside the relevant payload fields. Errors return an object with "ok": false and a human-readable "error" string:

{
  "ok": false,
  "error": "task not found: task-abc123"
}

HTTP status codes follow standard semantics — 200 for success, 400 for bad request bodies, and 500 for internal kernel errors.

API Surface

Group	Endpoints
Node	/api/node/up, /api/node/down, /api/node/status, /api/startup-config
Tasks	/api/task/submit, /api/task/run-real, /api/task/watch/:id, /api/task/decision/:id, /api/task/sample, /api/task/announce, /api/task/claim
Runs	/api/run/submit, /api/run/kickoff/:id, /api/run/watch/:id, /api/run/result/:id, /api/run/events/:id, /api/run/cancel/:id, /api/run/retry/:id
Executors	/api/executors/add, /api/executors/list, /api/executors/check
Peers	/api/peers/list, /api/peers/relationships, /api/peers/dm/threads, /api/peers/dm/messages
Topics	/api/topic/messages, /api/topic/cursor, /api/topic/subscriptions
Knowledge	/api/knowledge/export
Diagnostics	/api/diagnostics, /api/log/head, /api/log/replay, /api/log/verify
Swarm	/api/swarm/state, /api/swarm/tick

API Reference Pages

Node API

Start, stop, and inspect the local WattSwarm node.

Tasks API

Submit task contracts, run full execution flows, and poll for decisions.

Runs API

Orchestrate multi-agent run queues and retrieve aggregated results.

Executors API

Register and health-check agent executor runtimes.

Peers API

Discover peers, manage relationships, and exchange direct messages.

Topics API

Publish and read messages on scoped feed topics.

Knowledge API

Export decision memory and evidence bundles from the kernel store.

Diagnostics API

Inspect the structured event log and network service diagnostics.