入門指南

IVGraph API 說明文件

IVGraph 提供 REST API，讓你存取 Notion 工作空間的圖譜資料，包括節點、關係、搜尋及頁面內容。你可以用它開發整合功能、支援 LLM 代理運作，或透過程式分析你的 Notion 工作空間。

基底 URL

環境URL
正式環境https://ivgraph.com/api/
正式環境（V1）https://ivgraph.com/v1/

身分驗證

IVGraph 支援兩種身分驗證方式：

方式適用情境標頭
JWT（Notion OAuth） 網頁應用程式、使用者工作階段 Authorization: Bearer <jwt_access_token>
服務權杖 LLM 代理、自動化、CI/CD Authorization: Bearer ivg_<token>

使用服務權杖快速上手

  1. 透過 Notion OAuth 登入 ivgraph.com
  2. 前往「個人檔案 → 服務權杖」
  3. 建立權杖，並設定所需的權限範圍（例如 graph:search、graph:read）
  4. 在請求中使用權杖：
curl -H "Authorization: Bearer ivg_your_token_here" \
  "https://ivgraph.com/v1/graph/search?q=project&workspace_id=YOUR_WORKSPACE_ID"

API 分層

層級基底路徑身分驗證說明
V1 LLM API /v1/graph/ 服務權杖 供 LLM 代理以唯讀方式存取圖譜
圖譜 API /api/notion-graph/ JWT 完整圖譜資料（節點 + 邊）
搜尋 API /api/search/ JWT 全文、語意與混合搜尋
內部 API /api/ JWT 身分驗證、帳務、整合功能、樣式規則
公開 /api/stats/public/ 無 平台統計資料、健康狀態檢查

速率限制

API限制適用範圍
V1（服務權杖）突發請求上限為每 10 秒 20 次請求，每 15 分鐘上限為 600 次請求每個權杖
使用者 API（JWT）每分鐘 100 次請求每位使用者
匿名每分鐘 20 次請求每個 IP

錯誤格式

所有錯誤皆以 JSON 格式回傳：

{
  "error": "Short error message",
  "detail": "Extended description (optional)"
}

完整的錯誤參考資訊請見錯誤與速率限制。

適用於 LLM 代理

機器可讀的文件：