Flowith Kb

API Reference

엔드포인트

주의: 공식 문서의 모델 목록 경로(/seek-knowledge/models)는 404를 반환합니다. 실제 작동 경로는 /knowledge-base/models입니다.

Rate Limit

• 12 RPM (분당 12회 요청)
• 초과 시 HTTP 429 반환
• Flowith Credits 차감 과금

사용법

1. 지식 베이스 검색 (Non-Streaming)

curl -s -X POST "https://edge.flowith.net/external/use/knowledge-base/seek" \
  -H "Authorization: Bearer $FLOWITH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Host: edge.flowith.net" \
  -d '{
    "messages": [
      {"role": "user", "content": "<검색 질의>"}
    ],
    "model": "'"${FLOWITH_MODEL:-claude-opus-4.6}"'",
    "stream": false,
    "kb_list": ["'"$FLOWITH_KB_ID"'"]
  }'

응답 형식 (stream=false):

{
  "tag": "final",
  "content": "검색 결과 텍스트..."
}

2. 지식 베이스 검색 (Streaming)

curl -s -X POST "https://edge.flowith.net/external/use/knowledge-base/seek" \
  -H "Authorization: Bearer $FLOWITH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Host: edge.flowith.net" \
  -d '{
    "messages": [
      {"role": "user", "content": "<검색 질의>"}
    ],
    "model": "'"${FLOWITH_MODEL:-claude-opus-4.6}"'",
    "stream": true,
    "kb_list": ["'"$FLOWITH_KB_ID"'"]
  }'

스트리밍 응답 태그:

3. 사용 가능 모델 확인

curl -s -X GET "https://edge.flowith.net/external/use/seek-knowledge/models" \
  -H "Authorization: Bearer $FLOWITH_API_TOKEN" \
  -H "Host: edge.flowith.net"

4. 다중 턴 대화 (컨텍스트 유지)

curl -s -X POST "https://edge.flowith.net/external/use/knowledge-base/seek" \
  -H "Authorization: Bearer $FLOWITH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Host: edge.flowith.net" \
  -d '{
    "messages": [
      {"role": "user", "content": "파이썬 변수의 정의를 알려줘"},
      {"role": "assistant", "content": "변수는 데이터를 저장하는 이름 붙은 공간입니다..."},
      {"role": "user", "content": "그러면 타입 변환은 어떻게 하나요?"}
    ],
    "model": "'"${FLOWITH_MODEL:-claude-opus-4.6}"'",
    "stream": false,
    "kb_list": ["'"$FLOWITH_KB_ID"'"]
  }'

실전 활용 패턴

패턴 A: 단일 질의 검색

교안 작성 중 특정 개념을 참고자료에서 확인할 때:

# 환경변수 로드
source .agent/.env

# 검색 실행
RESULT=$(curl -s -X POST "https://edge.flowith.net/external/use/knowledge-base/seek" \
  -H "Authorization: Bearer $FLOWITH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Host: edge.flowith.net" \
  -d '{
    "messages": [{"role": "user", "content": "AI 시대의 서사에서 변수를 설명할 때 사용한 비유는 무엇인가?"}],
    "model": "claude-opus-4.6",
    "stream": false,
    "kb_list": ["'$FLOWITH_KB_ID_1'"]
  }')

echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['content'])"

패턴 B: 복수 KB 동시 검색

여러 지식 베이스를 동시에 검색할 때:

curl -s -X POST "https://edge.flowith.net/external/use/knowledge-base/seek" \
  -H "Authorization: Bearer $FLOWITH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Host: edge.flowith.net" \
  -d '{
    "messages": [{"role": "user", "content": "객체지향 프로그래밍의 캡슐화 개념을 설명해줘"}],
    "model": "claude-opus-4.6",
    "stream": false,
    "kb_list": ["'$FLOWITH_KB_ID_1'", "'$FLOWITH_KB_ID_2'"]
  }'

패턴 C: seeds 활용 (출처 추적)

스트리밍 모드에서 seeds 태그로 원본 출처를 확인할 때:

curl -s -X POST "https://edge.flowith.net/external/use/knowledge-base/seek" \
  -H "Authorization: Bearer $FLOWITH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Host: edge.flowith.net" \
  -d '{
    "messages": [{"role": "user", "content": "Antigravity IDE의 3-Surface 아키텍처란?"}],
    "model": "claude-opus-4.6",
    "stream": true,
    "kb_list": ["'$FLOWITH_KB_ID_1'"]
  }' 2>/dev/null | grep '"seeds"' | head -1

seeds 응답의 각 항목 구조:

{
  "id": "chunk_id",
  "tokens": 150,
  "content": "원본 텍스트 청크...",
  "order": 1,
  "source_id": "doc_id",
  "source_title": "문서 제목",
  "nip": 0.95
}

Lecture Factory 워크플로우 연동

A1 Source Miner에서 활용

팩트 패킷 추출 시 로컬 참고자료가 부족할 때 Flowith KB를 2차 소스로 활용:

[Step 1] 로컬 참고자료 분석 → 부족 판단
    ↓
[Step 2] Flowith KB 검색 (이 스킬)
    ↓
[Step 3] 딥리서치 (deep-research 스킬) — 여전히 부족할 때만

A2 Traceability Curator에서 활용

출처 검증 시 seeds 태그의 source_title과 content로 원본 추적:

검색 결과의 seeds → source_title로 원본 문서 식별
                  → content로 인용 텍스트 확인
                  → nip(관련도 점수)로 신뢰도 판단

Troubleshooting

Related Skills

• deep-research: 웹 전체 심층 리서치 (Flowith KB에 없는 정보)
• tavily-web: 웹 검색 (실시간 정보)
• context7-auto-research: 라이브러리/프레임워크 공식 문서
• firecrawl-scraper: 특정 웹페이지 구조화 데이터 추출