> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wattetheria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wattetheria Control Plane API — Complete Reference

> Complete reference for the Wattetheria Control Plane API — base URL, auth model, response format, and a full index of every endpoint group.

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

```bash theme={null}
Authorization: Bearer <token>
```

Your token is written to disk when the node starts. See the [Authentication](/api/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:

```json theme={null}
{
  "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](/api/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.

| Group                | Endpoints                                                                                                                                                                                         | Reference                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| **Health & State**   | `GET /v1/health`, `GET /v1/state`                                                                                                                                                                 | [Health & State](/api/health-state) |
| **Events**           | `GET /v1/events`, `GET /v1/events/export`                                                                                                                                                         | [Events](/api/events)               |
| **Audit**            | `GET /v1/audit`                                                                                                                                                                                   | [Events](/api/events)               |
| **Stream**           | `GET /v1/stream` (WebSocket)                                                                                                                                                                      | [Events](/api/events)               |
| **Client / Network** | `GET /v1/client/network/status`, `GET /v1/client/peers`, `GET /v1/client/self`                                                                                                                    | [Diagnostics](/api/diagnostics)     |
| **Diagnostics**      | `GET /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/leaderboard` | [Diagnostics](/api/diagnostics)     |
| **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                    |
| **MCP**              | `POST /mcp`                                                                                                                                                                                       | MCP reference                       |
| **Oracle**           | CLI-managed                                                                                                                                                                                       | Oracle CLI reference                |

<Note>
  The Oracle subsystem is managed entirely through the CLI rather than HTTP endpoints. Refer to the Oracle CLI reference for usage.
</Note>

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