REST-API-Referenz

Schreibgeschützte HTTP-API zum Abfragen gespeicherter Nostr-Events über GET /api/v1/... — Endpunkte, Parameter, Paginierung, Sichtbarkeitsregeln und Fehler.

Basis-URL

Die API wird unter /api/v1 auf demselben Port wie das WebSocket-Relay bereitgestellt:

text

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

Host-Routing (`server.api_host`)

Wenn server.api_host (z. B. api.example.com) konfiguriert ist, werden API und Relay per Host-Header getrennt: api.example.com erhält /api/v1, /health und /metrics; jeder andere Host erhält das WebSocket-Relay und NIP-11. Ohne api_host wird die API auf jedem Host bereitgestellt. Nur GET wird unterstützt — WebSocket-Upgrade-Anfragen an /api/v1 werden mit 403 abgelehnt.

Endpunkte

Identifikatorbasierte Pfade

Pfad	Gibt zurück
`GET /api/v1/<npub1...>`	Neuestes Kind-0-Profil-Event
`GET /api/v1/<note1>` / `<nevent1>`	Das einzelne Event mit dieser ID
`GET /api/v1/<naddr1>`	Events der Adresse (Kind + Autor + d-Tag)
`GET /api/v1/<npub1...>/<kind>`	Events nach Pubkey, gefiltert nach Kind (akzeptiert npub1... oder nprofile1...; sonst 400)

Autor-Identifikatoren akzeptieren auf jedem Endpunkt npub1..., nprofile1... oder einen 64-Hex-Pubkey (unabhängig von Groß-/Kleinschreibung).

Abfrage- und Aggregat-Endpunkte

GET /api/v1/query — generische Filterabfrage ohne Identifikator.
GET /api/v1/count — Gesamtanzahl für dieselben Filterparameter (NIP-45-Semantik).
GET /api/v1/<npub1...>/kinds — Event-Anzahlen pro Kind für einen Autor, meistgenutzte zuerst.
GET /api/v1/<npub1...>/<kind>/daily — Tagesanzahlen für einen Monat; Monat muss 1–12 sein, und jeder Tag wird mit Nullen aufgefüllt bis zum letzten Tag gemeldet (jeder Eintrag und die Summe tragen ein approximate-Flag).
GET /api/v1/ids/<hex> — ein einzelnes Event anhand seiner 64-Hex-ID (Präfixe abgelehnt).
GET /api/v1/<npub1...>/stats — Autor-Zusammenfassung (gesamt, erste/letzte Aktivität, Kind-Aufschlüsselung); first_seen/last_seen/Monate sind null, wenn keine sichtbaren Events existieren.
GET /api/v1/<npub1...>/<kind>/hourly — Stundenanzahlen für einen Tag; alle 24 Stunden werden mit Nullen aufgefüllt gemeldet (dieselben approximate-Flags wie bei daily).
GET /api/v1/ids/<hex>/related — Antworten (#e) und Zitate (#q), die auf das Event verweisen; die Pfad-ID wird vor dem Abgleich kleingeschrieben, und ein e-Abfrageparameter wird per OR in die #e-Seite einbezogen.
GET /api/v1/<npub1...>/follows — die neueste Kind-3-Folgeliste des Autors.
GET /api/v1/relay/kinds — die häufigsten Kinds auf dem Relay (begrenzte, sichtbarkeitsgefilterte Stichprobe; approximate- und filtered-Flags).
GET /api/v1/relay/top-authors — die aktivsten Autoren auf dem Relay (begrenzte, sichtbarkeitsgefilterte Stichprobe; approximate- und filtered-Flags).
GET /api/v1/<npub1...>/relays — die neueste NIP-65-Relay-Liste des Autors (Kind 10002).
GET /api/v1/<npub1...>/<kind>/monthly — Monatsanzahlen, mit Nullen aufgefüllt über den since/until-Bereich (Standard: der gesamte Zeitraum; begrenzt auf 120 Monate).

Abfrageparameter

Parameter	Beschreibung
`limit`	Max. Ergebnisse (Standard 100, begrenzt durch max_api_limit)
`offset`	Anzahl zu überspringender sichtbarer Ergebnisse (Paginierung)
`since`	Nur Events mit created_at >= since
`until`	Nur Events mit created_at <= until
`sort`	`asc`/`ascending` für älteste zuerst; Standard ist neueste zuerst
`search`	NIP-50-Volltextsuche (Ganzwortübereinstimmung)
`e` / `p` / `t` / `d`	Nach #e- / #p- / #t- / #d-Tags filtern
`no_p` / `no_e` / `no_t` / `no_d`	Events mit diesem Tag ausschließen — wird vor der Paginierung angewendet, sodass ausgeschlossene Events niemals Limit-Slots oder Offset-Schritte verbrauchen

Antwortformat

Erfolgreiche Antworten geben 200 OK mit folgendem JSON-Body zurück:

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
}

Feld	Beschreibung
`events`	Die Events dieser Seite (Standard: neueste zuerst)
`count`	Die Anzahl der Events auf dieser Seite
`more`	`true`, wenn weitere Seiten existieren (mit Offset abrufen)

Paginierung

Paginierung erfolgt mit offset und dem more-Flag, berechnet über die sichtbare Sequenz — verborgene Events überspringen oder duplizieren niemals eine Seite:

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

Endpunkt-Eigenheiten

Singleton-Endpunkte (Profil, /ids/{hex}, follows, relays) akzeptieren trotzdem offset — ?offset=1 überspringt das einzige Event und gibt [] zurück. Die Abfrageparameter authors/kinds filtern nur den generischen /query-Endpunkt: Auf Kind-Endpunkten werden sie stillschweigend ignoriert (beide sind vorbefüllt), während sie auf ID-Endpunkten per AND verknüpft werden. Die Kind-Aufschlüsselung von stats ist nach Kind geordnet, im Gegensatz zu /kinds (zuerst nach Anzahl).

Sichtbarkeitsregeln

Die API ist nicht authentifiziert und hält daher dieselben Events zurück wie eine anonyme WebSocket-Verbindung:

NIP-70-geschützte Events (mit --Tag)
NIP-59-Gift-Wraps (Kind 1059)
Private/verborgene NIP-29-Gruppeninhalte (nur für Mitglieder sichtbar)

Fehler und Statuscodes

Code	Bedeutung
200	Erfolg
400	Ungültiger Identifikator oder Abfrageparameter
403	WebSocket-Upgrade-Versuch an /api/v1
404	Unbekannter Pfad oder falscher Host für die API (api_host konfiguriert)
503	API-Nebenläufigkeitslimit erreicht — bitte gleich erneut versuchen

Beispiele

Notes eines Benutzers abrufen (neueste zuerst):

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

Paginieren und sortieren:

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

Ein einzelnes Event per ID abrufen (note1... oder nevent1... funktionieren beide):

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

Ein adressierbares Event abrufen (naddr1...):

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

Suche:

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

Tag-Filter:

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