시작하기

IVGraph API 문서

IVGraph는 노션 워크스페이스의 그래프 데이터(노드, 관계, 검색, 페이지 콘텐츠)에 접근할 수 있는 REST API를 제공해요. 통합을 구축하거나 LLM 에이전트를 구동하거나 코드로 노션 워크스페이스를 분석하는 데 활용할 수 있어요.

기본 URL

환경URL
프로덕션https://ivgraph.com/api/
프로덕션 (V1)https://ivgraph.com/v1/

인증

IVGraph는 두 가지 인증 방식을 지원해요.

방식용도헤더
JWT (노션 OAuth) 웹 앱, 사용자 세션 Authorization: Bearer <jwt_access_token>
서비스 토큰 LLM 에이전트, 자동화, CI/CD Authorization: Bearer ivg_<token>

서비스 토큰으로 빠르게 시작하기

  1. ivgraph.com에서 노션 OAuth로 로그인해요.
  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 에이전트용 문서

기계가 읽을 수 있는 문서: