검색 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}/

페이지 내용을 마크다운과 일반 텍스트로 가져와요.

매개변수:

매개변수	유형	필수 여부	설명
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를 사용할 수 없음