API Usage

JSON-RPC 2.0 basics

The router’s machine-callable API speaks JSON-RPC 2.0 over HTTP POST.

Via Unix socket (recommended for local tooling):

curl --unix-socket $PATH_SOCKET/hero_router/rpc.sock \
 -X POST http://localhost/rpc \
 -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":1,"method":"router.services","params":{}}'

Via TCP port (from a browser or remote host):

curl -X POST http://127.0.0.1:9988/rpc \
 -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":1,"method":"router.services","params":{}}'

Every request has the same shape:

{
 "jsonrpc": "2.0",
 "id": 1,
 "method": "<namespace>.<method>",
 "params": { ... }
}

Every response is either a result:

{ "jsonrpc": "2.0", "id": 1, "result": { ... } }

or an error:

{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32600, "message": "..." } }

Core router methods

router.services — list all discovered services

curl -s -X POST http://127.0.0.1:9988/rpc \
 -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":1,"method":"router.services","params":{}}' \
 | jq .result

Returns an array of service objects, each with:

router.service — detail for one service

curl -s -X POST http://127.0.0.1:9988/rpc \
 -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":1,"method":"router.service","params":{"id":"hero_proc"}}'

router.health — router health check

curl -s -X POST http://127.0.0.1:9988/rpc \
 -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":1,"method":"router.health","params":{}}'

Returns { "status": "ok", "uptime_secs": 1234 }.

router.cache.inspect — dump the full cache

curl -s -X POST http://127.0.0.1:9988/rpc \
 -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":1,"method":"router.cache.inspect","params":{}}'

router.manifest — fetch OpenRPC manifest for a service

curl -s -X POST http://127.0.0.1:9988/rpc \
 -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":1,"method":"router.manifest","params":{"id":"hero_db"}}'

The OpenRPC spec

The router publishes its own OpenRPC spec at:

GET http://127.0.0.1:9988/openrpc.json (via TCP / admin.sock)
GET http://localhost/openrpc.json (via rpc.sock)

This document describes every router.* method with full parameter and result schemas. Import it into any OpenRPC-compatible tool or client generator.

Proxying requests to a downstream service

Any service the router has discovered can be reached through the reverse proxy on the TCP port or admin.sock. The URL pattern is:

http://127.0.0.1:9988/<service_name>/<socket_stem>/<downstream_path>

Example — call job.list on hero_proc:

curl -X POST http://127.0.0.1:9988/hero_proc/rpc \
 -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":1,"method":"job.list","params":{}}'

Example — fetch hero_db’s OpenRPC spec through the router:

curl http://127.0.0.1:9988/hero_db/rpc/openrpc.json

Server-Sent Events (live updates)

Subscribe to the SSE stream to get real-time notifications when services are added, changed, or removed:

curl -N http://127.0.0.1:9988/api/sse

Events emitted: