사용자 가이드

이 가이드에서는 Schift를 가장 많이 사용하는 방법을 살펴 봅니다. 대시보드(dashboard), REST API, Python 및 TypeScript SDK, CLI, Model Context Protocol(MCP) 서버를 다룹니다.

시작하기 전에

Schift 계정과 API 키(API key)가 필요합니다. 아직 키가 없다면 {appUrl} 대시보드에서 생성하세요.

아래 예시 대부분은 환경 변수(environment variable)를 사용합니다.

export SCHIFT_API_KEY=sch_your_key_here
export SCHIFT_API_URL=<your-api-url>

이 환경에서는 SCHIFT_API_URL을 {apiUrl}(으)로 설정하세요. API 키는 비밀로 유지하고, 정기적으로 키를 교체하며, 환경별로 별도의 키를 사용하세요.

적절한 인터페이스(surface) 선택

인터페이스(surface)	적합한 용도	진입점(entry point)
Dashboard	키 관리, 결제, 버킷(bucket) 상태 확인	{appUrl}
REST API	직접 백엔드 통합(integration)	{apiUrl}
Python SDK	스크립트, 수집(ingestion), 검색(search), 마이그레이션	pip install schift
TypeScript SDK	TypeScript 또는 Node.js 애플리케이션	npm install @schift-io/sdk
CLI	반복 가능한 터미널 작업	pip install schift-cli
MCP	Claude Desktop 또는 Claude Code 연결	npx schift-mcp

빠른 설치 체크리스트

# Python SDK
pip install schift

# TypeScript SDK
npm install @schift-io/sdk

# CLI
pip install schift-cli
schift --help

# MCP server
npx schift-mcp

일반적인 워크플로우(workflow)

1. 대시보드에서 또는 POST /v2/buckets로 버킷(bucket)을 생성합니다.
2. POST /v2/buckets/{bucket_id}/documents로 버킷에 문서(documents)를 업로드합니다.
3. 인덱싱(indexing)이 끝날 때까지 기다리고, GET /v2/buckets/{bucket_id}/search/status로 준비 상태를 확인합니다.
4. POST /v2/buckets/{bucket_id}/search로 **버킷을 검색(search)**해 인용된 맥락(cited context)을 얻습니다.
5. POST /v1/chat으로 질문해 버킷(bucket) 기반 RAG 답변을 받습니다.

참고: 버킷 검색(Bucket search)은 업로드 우선, 수집 최적화 인터페이스입니다. 레거시(legacy) 통합(integration)에서만 POST /v1/collections/{name}/search를 사용하세요.

자주 사용하는 엔드포인트(endpoints)

• POST /v2/buckets
• POST /v2/buckets/{bucket_id}/documents
• GET /v2/buckets/{bucket_id}/search/status
• POST /v2/buckets/{bucket_id}/search
• POST /v1/chat
• POST /v1/chat/completions

인증(Authentication)

모든 API 요청은 Bearer 인증(Bearer authentication)을 사용합니다.

curl -H "Authorization: Bearer $SCHIFT_API_KEY" \
  $SCHIFT_API_URL/v2/buckets

SDK, CLI, MCP에서도 동일한 SCHIFT_API_KEY 값을 사용하세요. 그래야 같은 환경에서 서로 다른 키를 쓰지 않습니다.

다음 단계

• Buckets에서 지식을 생성하고 관리하세요.
• Bucket Search로 업로드한 콘텐츠를 검색하세요.
• RAG Chat로 근거 있는 답변을 받으세요.
• Chat Completions로 OpenAI 호환 요청을 라우팅하세요.
• 기존 통합(integration)을 마이그레이션하는 경우 Legacy Collections API를 참고하세요.

같이 보기

• Buckets
• Legacy Collections API
• RAG Chat
• Chat Completions