Référence de l’API REST

URL de base

L’API est servie sous /api/v1 sur le même port que le relais WebSocket :

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

Routage par hôte (server.api_host)

Lorsque server.api_host (p. ex. api.example.com) est configuré, l’API et le relais sont séparés par l’en-tête Host : api.example.com reçoit /api/v1, /health et /metrics ; tout autre hôte reçoit le relais WebSocket et NIP-11. Sans api_host, l’API est servie sur tous les hôtes. Seul GET est pris en charge — les demandes de mise à niveau WebSocket vers /api/v1 sont refusées avec 403.

Points de terminaison

Chemins basés sur un identifiant

Les identifiants d’auteur acceptent npub1..., nprofile1... ou une pubkey hexadécimale de 64 caractères (insensible à la casse) sur chaque point de terminaison.

Points de terminaison de requête et d’agrégation

• GET /api/v1/query — requête générique avec filtre sans identifiant.
• GET /api/v1/count — nombre total pour les mêmes paramètres de filtre (sémantique NIP-45).
• GET /api/v1/<npub1...>/kinds — nombres d’événements par kind pour un auteur, les plus utilisés d’abord.
• GET /api/v1/<npub1...>/<kind>/daily — nombres par jour pour un mois ; le mois doit être entre 1 et 12, et chaque jour est rapporté avec remplissage par zéro jusqu’au dernier jour (chaque entrée et le total portent un drapeau approximate).
• GET /api/v1/ids/<hex> — un événement unique par son id hexadécimal de 64 caractères (préfixes rejetés).
• GET /api/v1/<npub1...>/stats — résumé de l’auteur (total, première/dernière activité, répartition par kind) ; first_seen/last_seen/les mois valent null lorsqu’il n’existe aucun événement visible.
• GET /api/v1/<npub1...>/<kind>/hourly — nombres par heure pour un jour ; les 24 heures sont rapportées avec remplissage par zéro (mêmes drapeaux approximate que daily).
• GET /api/v1/ids/<hex>/related — réponses (#e) et citations (#q) référençant l’événement ; l’id du chemin est mis en minuscules avant comparaison, et un paramètre de requête e est combiné par OR avec le côté #e.
• GET /api/v1/<npub1...>/follows — la dernière liste de suivis kind-3 de l’auteur.
• GET /api/v1/relay/kinds — les kinds les plus courants sur le relais (échantillon borné, filtré par visibilité ; drapeaux approximate et filtered).
• GET /api/v1/relay/top-authors — les auteurs les plus actifs sur le relais (échantillon borné, filtré par visibilité ; drapeaux approximate et filtered).
• GET /api/v1/<npub1...>/relays — la dernière liste de relais NIP-65 de l’auteur (kind 10002).
• GET /api/v1/<npub1...>/<kind>/monthly — nombres par mois, avec remplissage par zéro sur la plage since/until (défaut : toute la période ; plafonné à 120 mois).

Paramètres de requête

Format de réponse

Les réponses réussies retournent 200 OK avec le corps JSON suivant :

{
  "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
}

Pagination

La pagination se fait avec offset et le drapeau more, calculés sur la séquence visible — les événements masqués ne sautent ni ne dupliquent jamais une page :

curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/1?limit=50&offset=0"     # page 1
curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/1?limit=50&offset=50"    # page 2 (quand more était vrai)

Règles de visibilité

L’API n’est pas authentifiée, elle retient donc les mêmes événements qu’une connexion WebSocket anonyme :

• Événements protégés NIP-70 (portant un tag -)
• Gift wraps NIP-59 (kind 1059)
• Contenu de groupe privé/masqué NIP-29 (visible uniquement par les membres)

Erreurs et codes de statut

Exemples

Récupérer les notes d’un utilisateur (les plus récentes d’abord) :

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

Paginer et trier :

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

Récupérer un événement unique par id (note1... ou nevent1... fonctionnent tous deux) :

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

Récupérer un événement adressable (naddr1...) :

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

Recherche :

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

Filtre par tag :

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