I2PControl API Documentation

I2PControl is a JSON-RPC 2.0 API bundled with the I2P router (since version 0.9.39). It enables authenticated monitoring and control of the router via structured JSON requests.

Default password: itoopie — this is the factory default and should be changed immediately for security.

1. Overview & Access

In the Java I2P case, you must go to Router Console → WebApps → I2PControl and enable it (set to start automatically).
Once active, all methods require that you first authenticate and receive a session token.

2. JSON-RPC Format

All requests follow the JSON-RPC 2.0 structure:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "MethodName",
  "params": {
    /* named parameters */
  }
}

A successful response includes a result field; on failure, an error object is returned:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": { /* data */ }
}

or

{
  "jsonrpc": "2.0",
  "id": "1",
  "error": {
    "code": -32001,
    "message": "Invalid password"
  }
}

3. Authentication Flow

Request (Authenticate)

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "1",
        "method": "Authenticate",
        "params": {
          "API": 1,
          "Password": "itoopie"
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

Successful Response

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "Token": "a1b2c3d4e5",
    "API": 1
  }
}

You must include that Token in all subsequent requests in the params.

4. Methods & Endpoints

4.1 RouterInfo

Fetches key telemetry about the router.

Request Example

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "2",
        "method": "RouterInfo",
        "params": {
          "Token": "a1b2c3d4e5",
          "i2p.router.version": "",
          "i2p.router.status": "",
          "i2p.router.net.status": "",
          "i2p.router.net.tunnels.participating": "",
          "i2p.router.net.bw.inbound.1s": "",
          "i2p.router.net.bw.outbound.1s": ""
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

Response Fields (result)
According to the official docs (GetI2P):

• i2p.router.status (String) — a human-readable status
• i2p.router.uptime (long) — milliseconds (or string for older i2pd) :contentReference[oaicite:0]{index=0}
• i2p.router.version (String) — version string :contentReference[oaicite:1]{index=1}
• i2p.router.net.bw.inbound.1s, i2p.router.net.bw.inbound.15s (double) — inbound bandwidth in B/s :contentReference[oaicite:2]{index=2}
• i2p.router.net.bw.outbound.1s, i2p.router.net.bw.outbound.15s (double) — outbound bandwidth in B/s :contentReference[oaicite:3]{index=3}
• i2p.router.net.status (long) — numeric status code (see enum below) :contentReference[oaicite:4]{index=4}
• i2p.router.net.tunnels.participating (long) — number of participating tunnels :contentReference[oaicite:5]{index=5}
• i2p.router.netdb.activepeers, fastpeers, highcapacitypeers (long) — netDB peer stats :contentReference[oaicite:6]{index=6}
• i2p.router.netdb.isreseeding (boolean) — whether reseed is active :contentReference[oaicite:7]{index=7}
• i2p.router.netdb.knownpeers (long) — total known peers :contentReference[oaicite:8]{index=8}

Status Code Enum (i2p.router.net.status)

4.2 GetRate

Used to fetch rate metrics (e.g. bandwidth, tunnel success) over a given time window.

Request Example

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "3",
        "method": "GetRate",
        "params": {
          "Token": "a1b2c3d4e5",
          "Stat": "bw.combined",
          "Period": 60000
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

Sample Response

{
  "jsonrpc": "2.0",
  "id": "3",
  "result": {
    "Rate": 12345.67
  }
}

4.3 RouterManager

Perform administrative actions.

Allowed parameters / methods

• Restart, RestartGraceful
• Shutdown, ShutdownGraceful
• Reseed, FindUpdates, Update :contentReference[oaicite:10]{index=10}

Request Example

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "4",
        "method": "RouterManager",
        "params": {
          "Token": "a1b2c3d4e5",
          "Restart": true
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

Successful Response

{
  "jsonrpc": "2.0",
  "id": "4",
  "result": {
    "Restart": null
  }
}

4.4 NetworkSetting

Get or set network configuration parameters (ports, upnp, bandwidth share, etc.)

Request Example (get current values)

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "5",
        "method": "NetworkSetting",
        "params": {
          "Token": "a1b2c3d4e5",
          "i2p.router.net.ntcp.port": null,
          "i2p.router.net.ssu.port": null,
          "i2p.router.net.bw.share": null,
          "i2p.router.net.upnp": null
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

Sample Response

{
  "jsonrpc": "2.0",
  "id": "5",
  "result": {
    "i2p.router.net.ntcp.port": "1234",
    "i2p.router.net.ssu.port": "5678",
    "i2p.router.net.bw.share": "50",
    "i2p.router.net.upnp": "true",
    "SettingsSaved": true,
    "RestartNeeded": false
  }
}

Note: i2pd versions prior to 2.41 may return numeric types instead of strings — clients should handle both. :contentReference[oaicite:11]{index=11}

4.5 AdvancedSettings

Allows manipulating internal router parameters.

Request Example

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "6",
        "method": "AdvancedSettings",
        "params": {
          "Token": "a1b2c3d4e5",
          "Set": {
            "router.sharePercentage": "75",
            "i2np.flushInterval": "6000"
          }
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

Response Example

{
  "jsonrpc": "2.0",
  "id": "6",
  "result": {
    "Set": {
      "router.sharePercentage": "75",
      "i2np.flushInterval": "6000"
    }
  }
}

5. Error Codes

In addition to standard JSON-RPC errors (-32700, -32600, etc.), I2PControl defines:

6. Usage & Best Practices

• Always include the Token parameter (except when authenticating).
• Change the default password (itoopie) upon first use.
• For Java I2P, ensure the I2PControl webapp is enabled via WebApps.
• Be prepared for slight variations: some fields may be numbers or strings, depending on I2P version.
• Wrap long status strings for display-friendly output.