Riferimento API REST

URL di base

L’API è servita sotto /api/v1 sulla stessa porta del relay WebSocket:

http://<host>:<port>/api/v1/{identifier}
http://<host>:<port>/api/v1/{identifier}/{kind}

Routing per host (server.api_host)

Quando server.api_host (es. api.example.com) è configurato, API e relay sono separati dall’header Host: api.example.com riceve /api/v1, /health e /metrics; qualsiasi altro host riceve il relay WebSocket e NIP-11. Senza api_host l’API è servita su ogni host. È supportato solo GET — le richieste di upgrade WebSocket a /api/v1 sono rifiutate con 403.

Endpoint

Percorsi basati su identificatore

Gli identificatori autore accettano npub1..., nprofile1... o una pubkey esadecimale da 64 caratteri (senza distinzione tra maiuscole e minuscole) su ogni endpoint.

Endpoint di query e aggregazione

• GET /api/v1/query — query generica con filtro senza identificatore.
• GET /api/v1/count — conteggio totale per gli stessi parametri di filtro (semantica NIP-45).
• GET /api/v1/<npub1...>/kinds — conteggi eventi per kind per un autore, prima i più usati.
• GET /api/v1/<npub1...>/<kind>/daily — conteggi giornalieri per un mese; il mese deve essere 1–12, e ogni giorno è riportato con riempimento a zero fino all’ultimo giorno (ogni voce e il totale portano un flag approximate).
• GET /api/v1/ids/<hex> — un singolo evento dal suo id esadecimale da 64 caratteri (prefissi rifiutati).
• GET /api/v1/<npub1...>/stats — riepilogo autore (totale, prima/ultima attività, suddivisione per kind); first_seen/last_seen/i mesi sono null quando non esistono eventi visibili.
• GET /api/v1/<npub1...>/<kind>/hourly — conteggi orari per un giorno; tutte le 24 ore sono riportate con riempimento a zero (stessi flag approximate di daily).
• GET /api/v1/ids/<hex>/related — risposte (#e) e citazioni (#q) che fanno riferimento all’evento; l’id del percorso è convertito in minuscolo prima del confronto, e un parametro di query e è combinato in OR nel lato #e.
• GET /api/v1/<npub1...>/follows — l’ultima lista seguiti kind-3 dell’autore.
• GET /api/v1/relay/kinds — i kind più comuni sul relay (campione limitato, filtrato per visibilità; flag approximate e filtered).
• GET /api/v1/relay/top-authors — gli autori più attivi sul relay (campione limitato, filtrato per visibilità; flag approximate e filtered).
• GET /api/v1/<npub1...>/relays — l’ultima lista relay NIP-65 dell’autore (kind 10002).
• GET /api/v1/<npub1...>/<kind>/monthly — conteggi mensili, con riempimento a zero sull’intervallo since/until (predefinito: l’intero periodo; massimo 120 mesi).

Parametri di query

Formato di risposta

Le risposte riuscite restituiscono 200 OK con il seguente corpo JSON:

{
  "events": [
    {
      "id": "32-byte hex event id",
      "pubkey": "32-byte hex pubkey",
      "created_at": 1700000000,
      "kind": 1,
      "tags": [["t", "example"]],
      "content": "hello",
      "sig": "64-byte hex signature"
    }
  ],
  "count": 1,
  "more": false
}

Paginazione

La paginazione avviene con offset e il flag more, calcolati sulla sequenza visibile — gli eventi nascosti non saltano né duplicano mai una pagina:

curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/1?limit=50&offset=0"     # pagina 1
curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/1?limit=50&offset=50"    # pagina 2 (quando more era true)

Regole di visibilità

L’API non è autenticata, quindi trattiene gli stessi eventi di una connessione WebSocket anonima:

• Eventi protetti NIP-70 (con tag -)
• Gift wrap NIP-59 (kind 1059)
• Contenuto di gruppo privato/nascosto NIP-29 (visibile solo ai membri)

Errori e codici di stato

Esempi

Recupera le note di un utente (prima le più recenti):

curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/1"

Pagina e ordina:

curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/1?limit=10&offset=10&sort=asc"

Recupera un singolo evento per id (funzionano sia note1... sia nevent1...):

curl "http://127.0.0.1:8080/api/v1/note1..."
curl "http://127.0.0.1:8080/api/v1/nevent1..."

Recupera un evento indirizzabile (naddr1...):

curl "http://127.0.0.1:8080/api/v1/naddr1..."

Cerca:

curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/1?search=rust"

Filtro per tag:

curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/7?e=<event-id>&limit=100"