REST API 參考

用於在 GET /api/v1/... 查詢已儲存 Nostr 事件的唯讀 HTTP API — 端點、參數、分頁、可見性規則與錯誤。

基礎 URL

API 在 /api/v1 下提供，與 WebSocket 中繼同一連接埠：

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>`	依公鑰、依類型過濾的事件（接受 npub1... 或 nprofile1...；否則 400）

作者識別碼在每個端點上接受 npub1...、nprofile1... 或 64 位十六進位公鑰（不分大小寫）。

查詢與聚合端點

GET /api/v1/query — 不帶識別碼的通用過濾器查詢。
GET /api/v1/count — 相同過濾器參數的總計數（NIP-45 語意）。
GET /api/v1/<npub1...>/kinds — 作者依類型的事件計數，最常用的在前。
GET /api/v1/<npub1...>/<kind>/daily — 某個月的按日計數； month 必須為 1-12，每天都以零填充回報到最後一天（每個條目與總計都帶 approximate 旗標）。
GET /api/v1/ids/<hex> — 依其 64 位十六進位 id 取得單一事件（拒絕前綴）。
GET /api/v1/<npub1...>/stats — 作者摘要（總計、首次/最後活動、類型細分）；沒有可見事件時 first_seen/last_seen/月份為 null。
GET /api/v1/<npub1...>/<kind>/hourly — 某一天的按小時計數；全部 24 小時都回報，零填充（與 daily 相同的 approximate 旗標）。
GET /api/v1/ids/<hex>/related — 參照該事件的回覆（#e）與引用（#q）；路徑 id 在比對前會轉為小寫，e 查詢參數會 OR 到 #e 一側。
GET /api/v1/<npub1...>/follows — 作者最新的 kind-3 關注清單。
GET /api/v1/relay/kinds — 中繼上最常見的類型（有界、可見性過濾的樣本；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 位元組十六進位事件 id",
      "pubkey": "32 位元組十六進位公鑰",
      "created_at": 1700000000,
      "kind": 1,
      "tags": [["t", "example"]],
      "content": "hello",
      "sig": "64 位元組十六進位簽章"
    }
  ],
  "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}、關注、中繼清單）仍接受 offset — ?offset=1 會略過唯一的事件並傳回 []。 authors/kinds 查詢參數只過濾通用的 /query 端點：在 kind 端點上它們被靜默忽略（兩者都已預填），而在 id 端點上它們被 AND 組合。stats 的類型細分依類型排序，不同於 /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"