JSON over HTTP. Below: reference for each route, then a live request panel. Base path is this host (e.g. /api/status).
Format. Responses use application/json. Successful bodies are plain objects (no data wrapper).
Errors. Failed requests return an object { "error": { "code": "<string>", "message": "<string>" } } with an appropriate HTTP status (400, 404, 500, 503, etc.).
Pubkey parameters. Path segments named :pubkey accept either a 64-character lowercase hex pubkey or an npub1… bech32 string (URL-encoded when used in a path).
Lightweight readiness check: runs SELECT 1 against PostgreSQL and returns process uptime.
| Status | Body |
|---|---|
200 | ok, service (nymrank-api), uptime_seconds |
503 | db_unavailable — database not reachable |
{}
Resolve whether a display name (and related nip05/lud16-style matches) is already associated with a ranked user. Only considers committee perspectives with rank_value ≥ 35 and requires a strong name match (affinity ≥ 2).
| Parameter | Description |
|---|---|
name | Path segment: trimmed and lowercased on the server. |
200 — available
{ "name": "alice", "available": true, "occupant": null }
200 — taken
{ "name": "alice", "available": false, "occupant": { "pubkey", "average_rank", "name_affinity", "profile": { "name", "nip05", "lud16" } } }
| Status | error.code |
|---|---|
400 | invalid_name |
500 | internal_error |
{}
Aggregated reputation for one user: averaged rank and influence metrics across committee rows, plus per-committee breakdown.
| Parameter | Description |
|---|---|
pubkey | Hex or npub (URL-encoded in path). |
200 — includes pubkey, average_rank, average_influence_score, average_hops, average_follower_count, perspective_count, profile (name, nip05, lud16, name_affinity), committee_breakdown (array of rows).
| Status | error.code |
|---|---|
400 | invalid_pubkey |
404 | not_found — no ranking row for this pubkey |
500 | internal_error |
{}
Ad-hoc pass over configured social relays: fetch recent events by this author (any kind), refresh kind 0 profile if present, and update profile_refresh_queue / activity timestamps in the database. Heavier than read-only APIs; may take a few seconds.
200 — pubkey (hex), latest_event (most recent relay event or null), total_events_found, profile (row from user_names + queue timestamps, or null if no profile row).
| Status | error.code |
|---|---|
400 | invalid_pubkey |
500 | internal_error — relay or processing failure |
{}