REST API リファレンス

保存済み Nostr イベントを GET /api/v1/... でクエリする読み取り専用 HTTP API — エンドポイント、パラメータ、ページネーション、可視性ルール、エラー。

ベース URL

API は WebSocket リレーと同じポートの /api/v1 配下で提供されます:

text

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

ホストルーティング (`server.api_host`)

server.api_host(例: api.example.com)が設定されている場合、API とリレーは Host ヘッダーで分離されます: api.example.com は /api/v1、 /health および /metrics を受け付け、それ以外のホストは WebSocket リレーと NIP-11 を受け付けます。 api_host がない場合、API はすべてのホストで提供されます。GET のみ対応 — /api/v1 への WebSocket アップグレード要求は 403 で拒否されます。

エンドポイント

識別子ベースのパス

パス	返却内容
`GET /api/v1/<npub1...>`	最新の kind-0 プロフィールイベント
`GET /api/v1/<note1>` / `<nevent1>`	この ID を持つ単一のイベント
`GET /api/v1/<naddr1>`	アドレスのイベント(kind + 作成者 + d タグ)
`GET /api/v1/<npub1...>/<kind>`	公開鍵によるイベントを kind でフィルタ(npub1... または nprofile1... を受け付け、それ以外は 400)

作成者識別子はすべてのエンドポイントで npub1...、nprofile1... または 64 文字 hex 公開鍵(大文字・小文字不問)を受け付けます。

クエリおよび集計エンドポイント

GET /api/v1/query — 識別子なしの汎用フィルタクエリ。
GET /api/v1/count — 同じフィルタパラメータに対する総件数(NIP-45 セマンティクス)。
GET /api/v1/<npub1...>/kinds — 作成者ごとの kind 別イベント件数、使用頻度の高い順。
GET /api/v1/<npub1...>/<kind>/daily — 1 か月分の日別件数。月は 1〜12 を指定します。すべての日は最終日までゼロ埋めで報告されます(各エントリと合計に approximate フラグ付き)。
GET /api/v1/ids/<hex> — 64 文字 hex ID による単一イベント(プレフィックスは拒否)。
GET /api/v1/<npub1...>/stats — 作成者サマリー(合計、最初/最後のアクティビティ、kind 内訳);可視イベントがない場合 first_seen/last_seen/月は null。
GET /api/v1/<npub1...>/<kind>/hourly — 1 日分の時間別件数;24 時間すべてがゼロ埋めで報告されます(daily と同じ approximate フラグ)。
GET /api/v1/ids/<hex>/related — イベントを参照するリプライ(#e)と引用(#q);パス ID は照合前に小文字化され、e クエリパラメータは #e 側に OR 結合されます。
GET /api/v1/<npub1...>/follows — 作成者の最新の kind-3 フォローリスト。
GET /api/v1/relay/kinds — リレー上で最も一般的な kind(上限あり、可視性フィルタ済みサンプル;approximate および filtered フラグ)。
GET /api/v1/relay/top-authors — リレー上で最もアクティブな作成者(上限あり、可視性フィルタ済みサンプル;approximate および filtered フラグ)。
GET /api/v1/<npub1...>/relays — 作成者の最新 NIP-65 リレーリスト(kind 10002)。
GET /api/v1/<npub1...>/<kind>/monthly — since/until 範囲に対する月別件数、ゼロ埋め(既定: 全期間;最大 120 か月)。

クエリパラメータ

パラメータ	説明
`limit`	最大件数(既定 100、max_api_limit が上限)
`offset`	スキップする可視結果の件数(ページネーション)
`since`	created_at >= since のイベントのみ
`until`	created_at <= until のイベントのみ
`sort`	古い順は `asc`／`ascending`。既定は新しい順
`search`	NIP-50 全文検索(完全一致)
`e` / `p` / `t` / `d`	#e / #p / #t / #d タグでフィルタ
`no_p` / `no_e` / `no_t` / `no_d`	そのタグを持つイベントを除外 — ページネーションの前に適用されるため、除外されたイベントは limit 枠や offset 歩数を消費しません

レスポンス形式

成功レスポンスは 200 OK と以下の JSON ボディを返します:

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
}

フィールド	説明
`events`	このページのイベント(既定は新しい順)
`count`	このページのイベント件数
`more`	後続ページがある場合は true(offset で取得)

ページネーション

ページネーションは offset と more フラグで行い、可視シーケンス上で計算されます — 非表示イベントによってページが飛んだり重複したりすることはありません:

curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/1?limit=50&offset=0"     # 1 ページ目です
curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/1?limit=50&offset=50"    # 2 ページ目です（more が true の場合）

エンドポイントの注意点

シングルトンエンドポイント(プロフィール、/ids/{hex}、follows、relays)でも offset を受け付けます — ?offset=1 は唯一のイベントをスキップして [] を返します。 authors/kinds クエリパラメータは汎用 /query エンドポイントのみをフィルタします: kind エンドポイントでは暗黙に無視され(両方とも事前入力済み)、ID エンドポイントでは AND 結合されます。stats の kind 内訳は kind 順であり、/kinds(件数順)とは異なります。

可視性ルール

API は認証なしのため、匿名 WebSocket 接続と同じイベントを秘匿します:

NIP-70 保護イベント(- タグ付き)
NIP-59 ギフトラップ(kind 1059)
NIP-29 プライベート/非公開グループコンテンツ(メンバーのみ可視)

エラーとステータスコード

コード	意味
200	成功
400	無効な識別子またはクエリパラメータ
403	/api/v1 への WebSocket アップグレード試行
404	不明なパス、または API に対する誤った Host(api_host 設定時)
503	API 同時実行数上限に達しました — しばらくして再試行してください

例

ユーザーのノートを取得(新しい順):

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

ページネーションとソート:

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

ID で単一イベントを取得(note1... も nevent1... も可):

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

アドレス指定可能イベントを取得(naddr1...):

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

検索:

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

タグフィルタ:

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