REST API Reference

Returns node health, persistent identity, peer counts (WS + relay), acceleration status, and network membership.

Response

{
  "status": "ok",
  "nodeId": "node-walk-forest-infinity-pq-xwEL",
  "persistentId": "yak-1100010T0:T100TT010:...",
  "peers": 1,
  "relayPeers": 2,
  "totalPeers": 3,
  "algorithm": "ML-DSA-65",
  "network": {
    "name": "walk-forest-infinity",
    "id": "pq-9dq7"
  },
  "sangha": {
    "state": "HARMONIOUS",
    "score": 1
  }
}

Returns AGUWA Kuramoto phase-coupling statistics — oscillator state, order parameter, per-peer phase, and dynamic capacity buffer. Also available at /time/aguwa.

{
  "initialized": true,
  "omega": 1.05,
  "orderParameter": 0.98,
  "health": "converged",
  "peerCount": 3,
  "correctionMs": 0.4,
  "networkJitter": 1.2,
  "entropyLinked": true,
  "buffer": {
    "peerCount": 3,
    "maxPeers": 128,
    "totalSlots": 160,
    "utilization": 0.023,
    "hasOverflow": false
  },
  "peers": [
    { "nodeId": "8cCG…", "theta": 0.0012, "timeTrust": 1.0,
      "propagationDelayMs": 14 }
  ],
  "divergentPeers": []
}

Returns SAMUHA admission-control status — capacity utilization, verdict tallies, and the live HOLD queue.

{
  "utilization": 0.45,
  "activePeers": 58,
  "maxPeers": 128,
  "verdicts": {
    "admit": 41,
    "hold": 3,
    "redirect": 1,
    "evictions": 0
  },
  "thresholds": {
    "hold": 0.8,
    "redirect": 1.0
  },
  "holdQueue": {
    "depth": 2,
    "maxDepth": 10,
    "timeoutMs": 30000,
    "waiting": [
      { "nodeId": "kP2x…", "priority": 0.412, "waitedMs": 8310 }
    ]
  }
}

Returns SANGHA collective attestation mesh status.

{
  "globalState": "HARMONIOUS",
  "components": {
    "CRYPTO": "HARMONIOUS",
    "MESH": "HARMONIOUS"
  },
  "fileGuardian": {
    "machineSeed": "valid",
    "nodeKey": "valid"
  }
}

Returns node identity information.

{
  "nodeId": "a7f3b2c1e8d9...",
  "name": "My YAKMESH Node",
  "region": "local",
  "algorithm": "ML-DSA-65",
  "nistLevel": 3,
  "publicKey": "3082...",
  "createdAt": "2026-01-17T10:00:00.000Z"
}

Lists all connected peers.

[
  {
    "nodeId": "b8e4c3f2a1d7...",
    "name": "Peer Node 1",
    "endpoint": "wss://peer1.example.com:9001",
    "lastSeen": 1737100000000
  },
  {
    "nodeId": "c9f5d4e3b2a8...",
    "name": "Peer Node 2",
    "endpoint": "inbound",
    "lastSeen": 1737100005000
  }
]

Returns network identity (derived from codebase hash, never exposing the hash).

{
  "name": "mobius-rabi-junction",
  "id": "pq-g1b6",
  "fingerprint": "8f3a9c2b...",
  "verificationPhrase": "The tier fermion reflects the create public"
}

Returns oracle status and self-integrity verification.

{
  "status": "healthy",
  "integrity": { "valid": true },
  "networkFingerprint": "8f3a9c2b...",
  "networkName": "mobius-rabi-junction",
  "networkId": "pq-g1b6",
  "validationMethods": ["hashContent", "verify", "seal"],
  "verifiedPeers": []
}

Spreads a rumor to connected peers via gossip protocol.

Request Body

{
  "topic": "custom_event",
  "data": { "key": "value" }
}

Response

{
  "success": true,
  "messageId": "msg_a7f3b2c1"
}

Returns SHERPA discovery service status and beacon information.

{
  "enabled": true,
  "beacon": {
    "nodeId": "a7f3b2c1e8d9...",
    "endpoint": "wss://node.example.com:9001",
    "lastBroadcast": 1737200000000
  },
  "discoveredPeers": 12,
  "beaconAge": "3d 4h 12m"
}

Returns list of discovered peer candidates for connection.

[
  {
    "nodeId": "b8e4c3f2a1d7...",
    "endpoint": "wss://peer1.example.com:9001",
    "karmaTier": "sathi",
    "lastSeen": 1737200000000
  }
]

Returns STUPA replication statistics.

{
  "status": "healthy",
  "peers": 5,
  "pendingSyncs": 0,
  "lastSync": 1737200000000,
  "replicatedItems": 1247
}

Stores data in the local node (rate limited).

Request Body

{
  "key": "my-content-key",
  "value": "content to store",
  "ttl": 86400
}

Response

{
  "success": true,
  "hash": "sha3-256-hash..."
}

Returns Universal Mesh Time with the effective time source — local GPS when locked, otherwise the mesh grandmaster received via time:heartbeat gossip, otherwise system clock. Also sets X-Yakmesh-Time/Stratum/Source response headers. Related: /api/time/simple, /time/status, /time/aguwa.

{
  "iso": "2026-09-23T21:30:28.884Z",
  "unix": 1790199028.884,
  "unix_ms": 1790199028884,
  "stratum": 1,
  "source": "MA-902/S-C1 GPS",
  "accuracy_ms": 1,
  "satellites": { "visible": 9, "used": 4, "tracking": 7, "constellations": ["GPS", "BeiDou"] },
  "lock": true,
  "quality": "excellent",
  "reference_id": "GPS",
  "public_ntp": "time.yakmesh.dev"
}

Lists local yak:// bookmarks (pet names for mesh resources). Also: GET /bookmarks/:name, POST /bookmarks, DELETE /bookmarks/:name.

{
  "count": 1,
  "bookmarks": [
    {
      "name": "docs",
      "yakUrl": "yak://docs",
      "target": "/docs",
      "httpUrl": "http://localhost:3080/docs",
      "createdAt": 1758400000000
    }
  ]
}

Remote bookmark sharing (gossip sync between subscribed nodes): GET /bookmarks/remote, GET /bookmarks/remote/status, POST /bookmarks/remote/subscribe, POST /bookmarks/remote/unsubscribe, POST /bookmarks/remote/publish.

Serves the documentation bundle (GRANTH). File integrity is verified against SHA3-256 hashes recorded in the bundle index at build time; metadata at /docs/_bundle.

Returns network identity, codebase fingerprint, peer compatibility counts, and pending upgrade state.

{
  "name": "walk-forest-infinity",
  "shortId": "pq-9dq7",
  "verificationPhrase": "A saber logarithm guides the pauli lamb",
  "fingerprint": "fb88f401c962...",
  "peers": { "compatible": 0, "incompatible": 0, "total": 0 },
  "pendingUpgrades": 0
}

Reports detected acceleration hardware and active backends. Values are measured, not assumed — npu is null when the node's own probe finds no NPU (NPU execution lives in the YakOS bridge, not the mesh node process). Detailed counters at /accel/telemetry.

{
  "hardware": {
    "cpu": "AMD Ryzen 7 8700F 8-Core Processor",
    "simd": { "avx512": true, "vaes": true, "shaNI": true, "gfni": true },
    "gpu": { "name": "NVIDIA GeForce RTX 3060", "cuda": "13.0", "tops": 101 },
    "npu": null,
    "totalTops": 101
  },
  "acceleration": {
    "sha3": "native (OpenSSL)",
    "pqCrypto": "pure-JS (@noble)",
    "inference": "cuda"
  }
}

Returns the live peer table. Also: /nakpak/status (circuit routing), /annex/status (PQ sessions), /sherpa/status, /api/claims/epoch/:epoch (epoch-batched claim root).