検索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を利用できません