Skip to main content
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}. 
POST /api/node/up
No request body is required. Example request: 
curl -X POST http://127.0.0.1:7788/api/node/up
Example response: 
{
  "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. 
POST /api/node/down
No request body is required. Example request: 
curl -X POST http://127.0.0.1:7788/api/node/down
Example response: 
{
  "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. 
GET /api/node/status
Example request: 
curl http://127.0.0.1:7788/api/node/status
Example response: 
{
  "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:
​
ok
boolean
true on success.
​
running
boolean
Whether the node is currently marked as online.
​
node_id
string
The stable identifier for this node derived from its identity keypair.
​
mode
string
Active network mode: "local", "lan", or "wan".
​
local_protocol_version
string
The WattSwarm protocol version string this kernel was built with.
​
peer_protocol_distribution
object
A map of protocol version strings to the number of peers currently running that version.

​
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. 
GET /api/startup-config
Example request: 
curl http://127.0.0.1:7788/api/startup-config
Example response: 
{
  "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:
​
config
object
The full startup configuration as persisted on disk.
​
core_agent_executor
string
The executor name currently active for the kernel’s own autonomous agent operations.

​
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. 
POST /api/startup-config
​
network_mode
string
required
Network connectivity mode. One of "local", "lan", or "wan".
​
bootstrap_contacts
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.
​
gateway_urls
string[]
Optional list of HTTP gateway URLs for nodes that cannot open inbound P2P connections directly.
​
core_agent
object
Specifies which executor and profile the kernel uses for its own autonomous agent operations.
Example request: 
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: 
{
  "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:
​
config
object
The full startup configuration as saved to disk.
​
core_agent_executor
string
The executor name currently active for the kernel’s own autonomous agent.
​
executor_registered
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.
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.