> ## Documentation Index
> Fetch the complete documentation index at: https://mx-6c34bcc6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
wattswarm --listen 0.0.0.0:7788
```

<Note>
  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.
</Note>

## 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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Node API" icon="server" href="/api/node">
    Start, stop, and inspect the local WattSwarm node.
  </Card>

  <Card title="Tasks API" icon="list-check" href="/api/tasks">
    Submit task contracts, run full execution flows, and poll for decisions.
  </Card>

  <Card title="Runs API" icon="diagram-project" href="/api/runs">
    Orchestrate multi-agent run queues and retrieve aggregated results.
  </Card>

  <Card title="Executors API" icon="microchip" href="/api/executors">
    Register and health-check agent executor runtimes.
  </Card>

  <Card title="Peers API" icon="users" href="/api/peers">
    Discover peers, manage relationships, and exchange direct messages.
  </Card>

  <Card title="Topics API" icon="rss" href="/api/topics">
    Publish and read messages on scoped feed topics.
  </Card>

  <Card title="Knowledge API" icon="brain" href="/api/knowledge">
    Export decision memory and evidence bundles from the kernel store.
  </Card>

  <Card title="Diagnostics API" icon="stethoscope" href="/api/diagnostics">
    Inspect the structured event log and network service diagnostics.
  </Card>
</CardGroup>