搜尋 API

全文搜尋

GET /api/search/

依標題與內容搜尋節點，並使用 BM25 排序。

參數：

參數	型別	必填	預設值	說明
q	string	是	—	搜尋查詢
connection_id	UUID	否	使用者的第一個連線	指定要搜尋的連線
size	int	否	50	結果數量上限
highlight	bool	否	true	包含醒目標示的內容片段
type	string	否	all	篩選條件：page、database 或 user

範例：

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/?q=project+planning&size=10"

import requests

resp = requests.get(
    "https://ivgraph.com/api/search/",
    headers={"Authorization": "Bearer <jwt_token>"},
    params={"q": "project planning", "size": 10}
)
results = resp.json()["results"]

const resp = await fetch(
  "https://ivgraph.com/api/search/?q=project+planning&size=10",
  { headers: { Authorization: "Bearer <jwt_token>" } }
);
const { results } = await resp.json();

回應：

{
  "query": "project planning",
  "total": 8,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "type": "page",
      "title": "Project Planning Guide",
      "score": 12.5,
      "highlight": "...comprehensive <em>project</em> <em>planning</em> methodology..."
    }
  ]
}

自動完成

GET /api/search/suggest/

根據前綴提供自動完成功能，支援邊輸入邊搜尋。

參數：

參數	型別	必填	預設值	說明
q	string	是	—	前綴（至少 2 個字元）
size	int	否	10	建議數量上限

範例：

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/suggest/?q=pro"

回應：

{
  "prefix": "pro",
  "suggestions": [
    {"id": "uuid-1", "title": "Project Alpha", "type": "page"},
    {"id": "uuid-2", "title": "Product Roadmap", "type": "page"},
    {"id": "uuid-3", "title": "Projects Tracker", "type": "database"}
  ]
}

語意搜尋

GET /api/search/semantic/

使用嵌入向量進行向量相似度搜尋，找出概念相近的內容，而不只是符合關鍵字的內容。

參數：

參數	型別	必填	預設值	說明
q	string	是	—	自然語言查詢
connection_id	UUID	否	使用者的第一個連線	要搜尋的連線
size	int	否	10	結果數量上限

範例：

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/semantic/?q=how+do+we+handle+user+onboarding"

回應：

{
  "query": "how do we handle user onboarding",
  "total": 5,
  "search_type": "semantic",
  "results": [
    {"id": "uuid-1", "type": "page", "title": "New User Welcome Flow", "score": 0.89},
    {"id": "uuid-2", "type": "page", "title": "Onboarding Checklist", "score": 0.82}
  ]
}

混合搜尋

GET /api/search/hybrid/

結合 BM25 關鍵字搜尋與語意向量搜尋，讓搜尋結果兼具兩者優勢。

參數：與語意搜尋相同。

範例：

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/hybrid/?q=authentication+flow"

相似節點

GET /api/search/similar/{node_id}/

根據嵌入向量，找出與指定節點相似的節點。

參數：

參數	型別	必填	預設值	說明
node_id	UUID	是	—	來源節點 ID（位於 URL 路徑中）
connection_id	UUID	否	使用者的第一個連線	要搜尋的連線
size	int	否	10	結果數量上限

範例：

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/similar/550e8400-e29b-41d4-a716-446655440001/"

頁面內容

GET /api/search/content/{page_id}/

取得 Markdown 與純文字格式的頁面內容。

參數：

參數	型別	必填	說明
page_id	UUID	是	頁面 ID（位於 URL 路徑中）

範例：

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/content/550e8400-e29b-41d4-a716-446655440001/"

回應：

{
  "page_id": "550e8400-e29b-41d4-a716-446655440001",
  "title": "Project Alpha",
  "markdown": "# Project Alpha\n\nMain project page...",
  "plain_text": "Project Alpha\nMain project page...",
  "has_content": true
}

索引管理

POST /api/search/index/

觸發使用者連線的 Elasticsearch 索引重建。

curl -X POST -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/index/"

回應：

{"message": "Indexing complete", "index_name": "ivg_conn-uuid", "indexed_count": 342}

DELETE /api/search/index/

刪除使用者連線的搜尋索引。

curl -X DELETE -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/index/"

GET /api/search/connections/

列出使用者的所有搜尋索引。

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/connections/"

回應：

{
  "user": "username",
  "connections": [
    {
      "connection_id": "conn-uuid",
      "schema_name": "airbyte_conn_uuid",
      "index_name": "ivg_conn-uuid",
      "document_count": 342,
      "last_sync": "2026-04-10T10:00:00Z"
    }
  ]
}

錯誤

狀態碼	意義
400	缺少查詢參數，或查詢參數無效
401	尚未通過身分驗證
404	找不到連線或頁面
503	Elasticsearch 無法使用