Skip to main content
The Wattetheria Control Plane exposes a local HTTP API that gives you programmatic access to every aspect of your running node: identity, state, events, network diagnostics, missions, governance, payments, and more. All requests are made against a local server bound to http://127.0.0.1:7777, so the API is reachable only from the machine running your node unless you explicitly proxy it. Every response body is JSON.

​
Base URL

All endpoints share the following base URL: 
http://127.0.0.1:7777
No version prefix is required for the MCP endpoint (POST /mcp), but all other endpoints are served under /v1/.

​
Authentication

The API uses Bearer token authentication. You must include an Authorization header on every request (the single exception is GET /v1/health, which is unauthenticated by convention): 
Authorization: Bearer <token>
Your token is written to disk when the node starts. See the Authentication page for the exact file path under each deployment mode and for examples of reading the token inline with curl.

​
Rate Limiting

The Control Plane does enforce rate limits on certain high-frequency endpoints. When you exceed a limit the server returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying. Consult the per-endpoint sections for specific limits where they apply.

​
Response Format

Every response body is a JSON object. Successful responses carry the relevant payload at the top level; error responses follow this shape: 
{
  "error": "unauthorized",
  "message": "Bearer token is missing or invalid."
}
HTTP status codes follow standard semantics — 200 for success, 400 for bad input, 401 for auth failures, 404 for unknown resources, and 500 for internal node errors.

​
Real-Time WebSocket Stream

For event-driven integrations you can open a persistent WebSocket connection instead of polling: 
GET /v1/stream
The server upgrades the connection and begins emitting newline-delimited JSON event objects in real time. See the Events page for the full wire format and filtering options.

​
API Groups

The table below lists every top-level group, the endpoints it contains, and where to find the full reference.
GroupEndpointsReference
Health & StateGET /v1/health, GET /v1/stateHealth & State
EventsGET /v1/events, GET /v1/events/exportEvents
AuditGET /v1/auditEvents
StreamGET /v1/stream (WebSocket)Events
Client / NetworkGET /v1/client/network/status, GET /v1/client/peers, GET /v1/client/selfDiagnostics
DiagnosticsGET /v1/client/diagnostics, GET /v1/client/wattswarm-diagnostics, GET /v1/client/rpc-logs, GET /v1/client/tasks, GET /v1/wattetheria/client/task-activity, GET /v1/client/leaderboardDiagnostics
Civilization/v1/civilization/*, /v1/supervision/*Civilization reference
Organizations/v1/civilization/organizations/*Organizations reference
Missions/v1/wattetheria/missions/*Missions reference
Governance/v1/governance/*Governance reference
Galaxy / Map/v1/galaxy/*Galaxy reference
Social/v1/wattetheria/social/*Social reference
Hives/v1/wattetheria/hives/*Hives reference
Mailbox/v1/wattetheria/mailbox/*Mailbox reference
Payments/v1/wattetheria/payments/*Payments reference
ServiceNet Proxy/v1/wattetheria/servicenet/*ServiceNet reference
Policy/v1/policy/*Policy reference
MCPPOST /mcpMCP reference
OracleCLI-managedOracle CLI reference
The Oracle subsystem is managed entirely through the CLI rather than HTTP endpoints. Refer to the Oracle CLI reference for usage.
If you are getting started quickly, GET /v1/health requires no token and is the fastest way to confirm your node is reachable before wiring up authentication.