버킷

버킷 생성

bashcurl -X POST https://api.schift.io/v1/buckets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{"name": "research-papers", "description": "ML 연구 논문 모음"}'

버킷 컬렉션

컬렉션은 버킷 안의 권한·검색 샤드입니다. 업로드는 특정 컬렉션을 대상으로 할 수 있고, 버킷 검색은 호출자가 검색 가능한 컬렉션만 먼저 계산한 뒤 실행됩니다.

bash# 하위 컬렉션 생성
curl -X POST https://api.schift.io/v1/buckets/{bucket_id}/collections \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{"name": "support-only", "description": "지원팀 전용 문서"}'

# 역할에 검색 권한 부여
curl -X POST https://api.schift.io/v1/buckets/{bucket_id}/collections/{collection_id}/grants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{"subject_type": "role", "subject_id": "support", "permission": "search"}'

파일 업로드

multipart form data로 하나 이상의 파일을 업로드합니다. 처리는 비동기로 진행되며, 엔드포인트는 job ID를 즉시 반환합니다.

bashcurl -X POST https://api.schift.io/v1/buckets/{bucket_id}/upload \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "collection_id={collection_id}" \
  -F "ocr_strategy=auto" \
  -F "chunk_size=512"

버킷 검색

bashcurl -X POST https://api.schift.io/v1/buckets/{bucket_id}/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{"query": "트랜스포머의 어텐션 메커니즘", "top_k": 5}'

검색은 권한 범위 안에서 실행됩니다. 서버가 호출자의 검색 가능 컬렉션을 계산하고, 해당 컬렉션들을 검색한 뒤 점수순으로 병합합니다. 결과에는 매칭된 텍스트 청크, 유사도 점수, 원본 파일명, 청크 메타데이터가 포함됩니다.

목록 조회 & 삭제

bash# 모든 버킷 조회
curl https://api.schift.io/v1/buckets \
  -H "Authorization: Bearer $SCHIFT_API_KEY"

# 버킷 삭제 (되돌릴 수 없음)
curl -X DELETE https://api.schift.io/v1/buckets/{bucket_id} \
  -H "Authorization: Bearer $SCHIFT_API_KEY"

엣지 (Edge) 관리

버킷 내 노드 간 관계를 정의합니다. 교육과정 순서, 판례 선례 관계, 문서 계층 구조 등을 표현할 수 있습니다.

bash# 엣지 추가
curl -X POST https://api.schift.io/v1/buckets/{bucket_id}/edges \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "edges": [
      {"source": "case-2024-456", "target": "case-2024-123", "relation": "supersedes"},
      {"source": "chapter-1", "target": "section-1-1", "relation": "has_child"}
    ]
  }'

# 노드의 엣지 조회
curl https://api.schift.io/v1/buckets/{bucket_id}/edges/{node_id}?direction=both \
  -H "Authorization: Bearer $SCHIFT_API_KEY"

# 엣지 삭제
curl -X DELETE https://api.schift.io/v1/buckets/{bucket_id}/edges \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{"source": "A", "target": "B", "relation": "related_to"}'