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

# Node API — Start, Stop, and Inspect the WattSwarm Kernel

> HTTP endpoints for bringing the WattSwarm node up and down, querying live runtime status, and reading or saving the startup configuration.

The Node API controls the lifecycle of the local WattSwarm kernel process. Use these endpoints to bring the node online or offline, inspect its current runtime state, and read or update the startup configuration that governs network mode, bootstrap contacts, and the core agent binding. All endpoints are relative to the kernel base URL (default `http://127.0.0.1:7788`).

***

## POST /api/node/up

Brings the node online. The kernel opens the configured node identity, writes a running state to disk, and starts the background network service if networking is enabled. Calling this endpoint when the node is already up is safe and returns `{"ok": true}`.

```bash theme={null}
POST /api/node/up
```

No request body is required.

**Example request:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/node/up
```

**Example response:**

```json theme={null}
{
  "ok": true
}
```

***

## POST /api/node/down

Brings the node offline. The running flag is written to disk as `false`; the background network service is not forcefully torn down but will not be restarted until `/api/node/up` is called again.

```bash theme={null}
POST /api/node/down
```

No request body is required.

**Example request:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/node/down
```

**Example response:**

```json theme={null}
{
  "ok": true
}
```

***

## GET /api/node/status

Returns the current runtime state of the node, including the node identity, network mode, protocol version, and the distribution of protocol versions seen among connected peers.

```bash theme={null}
GET /api/node/status
```

**Example request:**

```bash theme={null}
curl http://127.0.0.1:7788/api/node/status
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "running": true,
  "node_id": "node-f3a2bc91d04e5678abcd1234ef567890",
  "mode": "wan",
  "local_protocol_version": "wattswarm/1.0.0",
  "peer_protocol_distribution": {
    "wattswarm/1.0.0": 4,
    "wattswarm/0.9.0": 1
  }
}
```

**Response fields:**

<ResponseField name="ok" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="running" type="boolean">
  Whether the node is currently marked as online.
</ResponseField>

<ResponseField name="node_id" type="string">
  The stable identifier for this node derived from its identity keypair.
</ResponseField>

<ResponseField name="mode" type="string">
  Active network mode: `"local"`, `"lan"`, or `"wan"`.
</ResponseField>

<ResponseField name="local_protocol_version" type="string">
  The WattSwarm protocol version string this kernel was built with.
</ResponseField>

<ResponseField name="peer_protocol_distribution" type="object">
  A map of protocol version strings to the number of peers currently running that version.
</ResponseField>

***

## GET /api/startup-config

Returns the persisted startup configuration from disk. This configuration is read on every node start and controls how the kernel connects to the network.

```bash theme={null}
GET /api/startup-config
```

**Example request:**

```bash theme={null}
curl http://127.0.0.1:7788/api/startup-config
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "config": {
    "network_mode": "wan",
    "bootstrap_contacts": [
      "iroh-bootstrap-contact-1"
    ],
    "gateway_urls": [],
    "core_agent": {
      "executor": "local-agent",
      "profile": "default"
    }
  },
  "core_agent_executor": "local-agent"
}
```

**Response fields:**

<ResponseField name="config" type="object">
  The full startup configuration as persisted on disk.
</ResponseField>

<ResponseField name="core_agent_executor" type="string">
  The executor name currently active for the kernel's own autonomous agent operations.
</ResponseField>

***

## POST /api/startup-config

Saves a new startup configuration to disk. Changes take effect on the next node restart; they do not hot-reload while the node is running.

```bash theme={null}
POST /api/startup-config
```

<ParamField body="network_mode" type="string" required>
  Network connectivity mode. One of `"local"`, `"lan"`, or `"wan"`.
</ParamField>

<ParamField body="bootstrap_contacts" type="string[]">
  List of bootstrap contact strings used to join the peer-to-peer overlay. Typically these are iroh-style contact tokens shared by known bootnodes.
</ParamField>

<ParamField body="gateway_urls" type="string[]">
  Optional list of HTTP gateway URLs for nodes that cannot open inbound P2P connections directly.
</ParamField>

<ParamField body="core_agent" type="object">
  Specifies which executor and profile the kernel uses for its own autonomous agent operations.

  <Expandable title="core_agent fields">
    <ParamField body="executor" type="string">
      Name of the registered executor to use (see [Executors API](/api/executors)).
    </ParamField>

    <ParamField body="profile" type="string">
      Executor profile name; defaults to `"default"`.
    </ParamField>
  </Expandable>
</ParamField>

**Example request:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/startup-config \
  -H "Content-Type: application/json" \
  -d '{
    "network_mode": "wan",
    "bootstrap_contacts": ["iroh-bootstrap-contact-1"],
    "gateway_urls": [],
    "core_agent": {
      "executor": "local-agent",
      "profile": "default"
    }
  }'
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "config": {
    "network_mode": "wan",
    "bootstrap_contacts": ["iroh-bootstrap-contact-1"],
    "gateway_urls": [],
    "core_agent": {
      "executor": "local-agent",
      "profile": "default"
    }
  },
  "core_agent_executor": "local-agent",
  "executor_registered": false
}
```

**Response fields:**

<ResponseField name="config" type="object">
  The full startup configuration as saved to disk.
</ResponseField>

<ResponseField name="core_agent_executor" type="string">
  The executor name currently active for the kernel's own autonomous agent.
</ResponseField>

<ResponseField name="executor_registered" type="boolean">
  `true` if the `core_agent` executor entry was automatically registered (or updated) in the executor registry as a result of this save. `false` when `core_agent` was not changed.
</ResponseField>

<Tip>
  After saving a new startup configuration, call `POST /api/node/down` followed by `POST /api/node/up` to apply it without restarting the kernel process.
</Tip>