HTTP APIs
relay-api routes, relay-agent REST, and how the panel proxies to the Web Server.
HTTP API reference
This page consolidates relay-api (Web Server) and relay-agent (Relay Server Agent) routes. relay-panel proxies through its own /api/* routes — see the table under relay-panel.
relay-api (Hono, Web Server)
Base URL example: https://relay-api.bitmacro.io
Auth (panel / connect proxy):
| Method | Header(s) |
|---|---|
| API key | X-API-Key + X-Provider-User-Id |
| JWT | Authorization: Bearer <token> (NextAuth session clients) |
Relays and config
| Route | Method | Description |
|---|---|---|
/relays | GET | List relays for provider_user_id |
/relays | POST | Create relay |
/relay/:id | PATCH | Update relay |
/relay/:id | DELETE | Delete relay |
/relay-update | PATCH | Alternative update: body { id, name?, endpoint?, token? } |
/relay/:id/config | GET | Endpoint + token (for UI) |
/me | GET | JWT payload / session |
Proxy → agent
| Route | Method | Description |
|---|---|---|
/relay/:id/stats | GET | Proxy → agent /stats |
/relay/:id/health | GET | Proxy → agent /health |
/relay/:id/events | GET | Proxy → agent /events |
/relay/:id/probe | GET | Connectivity test |
/relay/:id/policy | GET | Proxy → agent /policy |
/relay/:id/users | GET | Proxy → agent /users |
/relay/:id/policy/block | POST | Proxy → agent |
/relay/:id/policy/allow | POST | Proxy → agent |
Proxy mechanics: relay-api reads endpoint, token, and agent_relay_id from relay.relay_configs, then calls GET/POST ${endpoint}${path} with Authorization: Bearer ${token}. Paths include the /:relayId/ prefix for v0.2 multi-relay agents.
NIP-46 /signer
Same handlers are also mounted under /api/signer/*.
| Route | Method | Description |
|---|---|---|
/signer/config | GET | Relays available for NIP-46 for this provider_user_id |
/signer/connect | POST | Create nip46_sessions row + nostrconnect_uri |
/signer/sessions | GET | List sessions (polling) |
/signer/session/:id/complete | POST | Verify pairing secret → active |
/signer/session/:id | DELETE | Revoke session |
relay-agent (strfry REST)
v0.2 multi-relay: path prefix /:relayId/. v0.1: same routes without prefix when RELAY_INSTANCES is unset.
Global
| Route | Method | Auth | Description |
|---|---|---|---|
/health | GET | — | e.g. { status: "ok", relayIds?: [...], version? } |
/:relayId/health | GET | — | Per-relay health (v0.2) |
Authenticated (Bearer)
| Route | Method | Description |
|---|---|---|
/:relayId/stats | GET | Events count, DB size, uptime, version |
/:relayId/events | GET | Query strfry / events |
/:relayId/events/:id | DELETE | Delete event |
/:relayId/policy | GET | Write policy |
/:relayId/policy/block | POST | Block pubkey + optional cleanup |
/:relayId/policy/allow | POST | Allow pubkey |
/:relayId/users | GET | Users / pubkeys |
Repositories
| Repo | Role | License |
|---|---|---|
| relay-agent | REST → strfry | MIT |
| relay-connect | SDK NIP-46 / NIP-07 | MIT |
| relay-connect-web | Connect UI | MIT |
| relay-panel | Admin UI | BSL 1.1 |
| relay-api | Hub + Supabase + proxy + /signer | Private |
Planned: @bitmacro/connect on npm — shared client for /signer and NIP-46 helpers for relay-panel, relay-connect-web, and third-party frontends.
Supply chain (summary)
| Repo | Typical automation |
|---|---|
| relay-agent | CI (Vitest); tag v*.*.* → npm + GHCR |
| relay-panel | CI lint + build; Vercel deploy |
| relay-connect | CI / build; Vercel typical |
| relay-api | Vercel deploy |
npm org @bitmacro; images ghcr.io/bitmacro/*.