콘텐츠로 이동
Schift Docs

버킷

Show:

**버킷(bucket)**은 Schift의 공개 지식 저장소 공간입니다. 버킷을 사용하면 문서를 업로드하고, 인덱싱 준비 상태를 확인하고, 출처가 포함된 답변용 맥락을 검색하고, 지식 기반에 속한 문서를 관리할 수 있습니다.

참고: 모든 버킷 엔드포인트는 Authorization: Bearer <SCHIFT_API_KEY> 헤더가 필요합니다. 버킷이나 문서를 생성·수정·삭제하는 엔드포인트는 buckets:manage 스코프(scope)가 필요합니다. 읽기 및 검색 엔드포인트는 조직 제한 내에서 유효한 API 키만으로 사용할 수 있습니다.

API 버전

섹션 제목: “API 버전”

공개 제품 API는 v2입니다. 신규 연동은 아래 문서화된 /v2/buckets/* 경로를 사용해야 합니다.

기존 /v1/buckets/* 경로는 이전 클라이언트를 위한 폐기 예정 호환성 레이어입니다. 여전히 동작하지만, v1 검색 엔드포인트는 Deprecation 및 Link 후속 버전 헤더를 반환하여 v2 대응 엔드포인트를 안내합니다. 공개 버킷(public bucket)은 두 버전 모두에서 읽기 전용입니다.

버킷 객체

섹션 제목: “버킷 객체”
필드타입설명
idstring고유한 버킷 식별자입니다.
namestring사람이 읽을 수 있는 버킷 이름입니다.
descriptionstring선택적 설명입니다.
dimensioninteger버킷에 설정된 임베딩 차원(embedding dimension)입니다.
modelstring버킷에 사용된 임베딩 모델(embedding model)입니다.
backendstring벡터 백엔드(vector backend)입니다. 예: engine.
file_countinteger업로드된 문서 수입니다.
vector_countinteger인덱싱된 벡터 수입니다.
active_job_countinteger해당 버킷의 진행 중인 작업 수입니다.
created_atstringISO 8601 생성 시각입니다.
default_privacy_levelinteger버킷 콘텐츠의 기본 프라이버시 수준입니다.
max_privacy_levelinteger허용된 최대 프라이버시 수준입니다.
external_max_privacy_levelinteger외부에 노출되는 최대 프라이버시 수준입니다.
enforce_access_policyboolean접근 정책(access policy)을 강제하는지 여부입니다.
enforce_document_aclboolean문서별 접근 규칙(deny 우선 적용, 규칙이 없는 문서는 기본 공개)을 검색에 적용할지 여부입니다.
scope_by_departmentboolean부서 메타데이터로 접근 범위를 제한하는지 여부입니다.

POST /v2/buckets

섹션 제목: “POST /v2/buckets”

새 버킷을 생성합니다. Schift가 임베딩 모델, 차원, 백엔드를 자동으로 구성합니다.

요청 본문

섹션 제목: “요청 본문”
필드타입필수기본값설명
namestring예—버킷 이름입니다. __schift_로 시작할 수 없습니다.
descriptionstring아니오""선택적 설명입니다.
metadataobject아니오null자유 형식의 사용자 메타데이터입니다.
default_privacy_levelinteger아니오3기본 프라이버시 수준입니다.
max_privacy_levelinteger아니오10최대 프라이버시 수준입니다.
external_max_privacy_levelinteger아니오1외부 프라이버시 상한입니다.
enforce_access_policyboolean아니오true접근 정책 강제를 활성화합니다.
enforce_document_aclboolean아니오false문서별 접근 규칙(deny 우선 적용, 규칙이 없는 문서는 기본 공개)을 검색에 적용합니다.
scope_by_departmentboolean아니오false부서별 접근 범위를 적용합니다.

요청 예시

섹션 제목: “요청 예시”
{
  "name": "product-docs",
  "description": "Product support knowledge"
}

응답 예시

섹션 제목: “응답 예시”
{
  "id": "bucket_01J8X1234567890ABCDEF",
  "name": "product-docs",
  "description": "Product support knowledge",
  "dimension": 1024,
  "model": "text-embedding-3-large",
  "backend": "engine",
  "file_count": 0,
  "vector_count": 0,
  "active_job_count": 0,
  "created_at": "2026-06-19T05:00:00Z",
  "default_privacy_level": 3,
  "max_privacy_level": 10,
  "external_max_privacy_level": 1,
  "enforce_access_policy": false,
  "enforce_document_acl": false,
  "scope_by_department": false
}

오류

섹션 제목: “오류”
상태원인
400잘못된 요청 본문입니다.
403버킷 이름이 예약된 __schift_ 네임스페이스를 사용합니다.
409동일한 이름의 버킷이 이미 존재합니다.

GET /v2/buckets

섹션 제목: “GET /v2/buckets”

인증된 조직의 버킷 목록을 조회합니다.

응답 예시

섹션 제목: “응답 예시”
[
  {
    "id": "bucket_01J8X1234567890ABCDEF",
    "name": "product-docs",
    "description": "Product support knowledge",
    "dimension": 1024,
    "model": "text-embedding-3-large",
    "backend": "engine",
    "file_count": 12,
    "vector_count": 128,
    "active_job_count": 0,
    "created_at": "2026-06-19T05:00:00Z",
    "default_privacy_level": 3,
    "max_privacy_level": 10,
    "external_max_privacy_level": 1,
    "enforce_access_policy": false,
    "enforce_document_acl": false,
    "scope_by_department": false
  }
]

GET /v2/buckets/{bucket_id}

섹션 제목: “GET /v2/buckets/{bucket_id}”

ID로 단일 버킷을 조회합니다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
bucket_idstring예버킷 식별자입니다.

응답 예시

섹션 제목: “응답 예시”

POST /v2/buckets 응답과 동일한 형식입니다.

오류

섹션 제목: “오류”
상태원인
404버킷을 찾을 수 없거나 접근할 수 없습니다.

PATCH /v2/buckets/{bucket_id}

섹션 제목: “PATCH /v2/buckets/{bucket_id}”

변경 가능한 버킷 필드를 수정합니다. 현재 이름 변경, 설명 업데이트, 그리고 프라이버시 정책 필드를 포함한 메타데이터 업데이트를 지원합니다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
bucket_idstring예버킷 식별자입니다.

요청 본문

섹션 제목: “요청 본문”

모든 필드는 선택적입니다.

필드타입설명
namestring새 버킷 이름입니다.
descriptionstring새 설명입니다.
metadataobject기존 메타데이터에 병합되는 자유 형식 메타데이터입니다.
default_privacy_levelinteger기본 프라이버시 수준입니다.
max_privacy_levelinteger최대 프라이버시 수준입니다.
external_max_privacy_levelinteger외부 프라이버시 상한입니다.
enforce_access_policyboolean접근 정책 강제를 활성화합니다.
enforce_document_aclboolean문서별 접근 규칙(deny 우선 적용, 규칙이 없는 문서는 기본 공개)을 검색에 적용합니다.
scope_by_departmentboolean부서별 접근 범위를 적용합니다.

요청 예시

섹션 제목: “요청 예시”
{
  "description": "Updated product support knowledge"
}

응답 예시

섹션 제목: “응답 예시”

POST /v2/buckets 응답과 동일한 형식입니다.

오류

섹션 제목: “오류”
상태원인
403공개 버킷은 읽기 전용입니다.
404버킷을 찾을 수 없습니다.
409새 버킷 이름이 이미 사용 중입니다.

DELETE /v2/buckets/{bucket_id}

섹션 제목: “DELETE /v2/buckets/{bucket_id}”

버킷 삭제를 큐에 넣습니다. 삭제는 비동기로 수행되며 작업 ID(job ID)를 반환합니다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
bucket_idstring예버킷 식별자입니다.

응답 예시

섹션 제목: “응답 예시”
{
  "bucket_id": "bucket_01J8X1234567890ABCDEF",
  "job_id": "job_01J8Y1234567890ABCDEF",
  "status": "queued",
  "delete_requested_at": "2026-06-19T05:05:00Z"
}

오류

섹션 제목: “오류”
상태원인
403공개 버킷은 읽기 전용입니다.
404버킷을 찾을 수 없습니다.

GET /v2/buckets/{bucket_id}/collections

섹션 제목: “GET /v2/buckets/{bucket_id}/collections”

버킷 내부의 하위 컬렉션(collection) 목록을 조회합니다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
bucket_idstring예버킷 식별자입니다.

응답 예시

섹션 제목: “응답 예시”
[
  {
    "id": "col_01J8X1234567890ABCDEF",
    "bucket_id": "bucket_01J8X1234567890ABCDEF",
    "name": "migration-guides",
    "description": "",
    "dimension": 1024,
    "model": "text-embedding-3-large",
    "backend": "engine",
    "file_count": 4,
    "vector_count": 42,
    "active_job_count": 0
  }
]

오류

섹션 제목: “오류”
상태원인
404버킷을 찾을 수 없습니다.

GET /v2/buckets/{bucket_id}/search/status

섹션 제목: “GET /v2/buckets/{bucket_id}/search/status”

버킷이 질문에 답할 준비가 되었는지 확인합니다. 이 엔드포인트는 검색을 실행하지 않고, 최종 사용자용 준비 상태 요약을 반환합니다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
bucket_idstring예버킷 식별자입니다.

응답 예시

섹션 제목: “응답 예시”
{
  "status": "ready",
  "operational_status": "ready",
  "bucket_id": "product-docs",
  "indexed_count": 128,
  "document_count": 12,
  "pending_job_count": 0,
  "failed_job_count": 0,
  "last_indexed_at": "2026-06-19T04:55:00Z",
  "backfill_required": false
}

오류

섹션 제목: “오류”
상태원인
404버킷을 찾을 수 없습니다.

POST /v2/buckets/{bucket_id}/search

섹션 제목: “POST /v2/buckets/{bucket_id}/search”

관리형 지식 검색 파이프라인(managed knowledge-search pipeline)을 실행하고, 출처가 포함된 답변용 맥락을 반환합니다. 호출자가 임베딩 경로, 벡터 모드, 재정렬(re-rank) 방식을 직접 선택할 필요는 없습니다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
bucket_idstring예버킷 식별자입니다.

요청 본문

섹션 제목: “요청 본문”
필드타입필수기본값설명
querystring예—버킷에 대해 질문할 내용입니다.
top_kinteger아니오8반환할 최대 인용 구절 수입니다. 범위: 1–100.
context_budgetinteger아니오2000토큰 단위의 대략적인 최대 맥락 크기입니다. 범위: 100–32000.
filtersobject아니오null메타데이터 필터입니다. 자세한 내용은 필터를 참고하세요.
options.rerank.enabledboolean아니오true맥락 조립 전 인용 순서를 개선합니다.
options.rerank.top_kinteger아니오null재정렬할 후보 구절 수입니다. 범위: 1–1000.
options.instructions.taskstring아니오nullretrieval_query 같은 검색 지시 프리셋입니다.

요청 예시

섹션 제목: “요청 예시”
{
  "query": "How do I migrate embedding models?",
  "top_k": 8,
  "context_budget": 4000,
  "filters": {"product": "schift"},
  "options": {
    "rerank": {"enabled": true, "top_k": 20},
    "instructions": {"task": "retrieval_query"}
  }
}

응답 예시

섹션 제목: “응답 예시”
{
  "status": "ready",
  "operational_status": "ready",
  "bucket_id": "product-docs",
  "query": "How do I migrate embedding models?",
  "context": "[1] Migration guide excerpt...",
  "citations": [
    {
      "index": 1,
      "document_id": "doc_042",
      "source_id": "doc_042",
      "title": "Migration Guide",
      "source_url": null,
      "page": null,
      "section": null
    }
  ],
  "warnings": []
}

오류

섹션 제목: “오류”
상태원인
400잘못된 필터 또는 요청 본문입니다.
402검색 할당량을 초과했습니다.
403검색 할당량을 사용할 수 없거나 플랜 제한입니다.
404버킷을 찾을 수 없습니다.

POST /v2/buckets/{bucket_id}/collections/{collection_id}/search

섹션 제목: “POST /v2/buckets/{bucket_id}/collections/{collection_id}/search”

원시 v2 검색 규약(raw v2 search contract)을 사용하여 버킷 내 단일 컬렉션을 검색합니다. 전체 버킷이 아닌 특정 하위 컬렉션의 결과만 원할 때 유용합니다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
bucket_idstring예버킷 식별자입니다.
collection_idstring예컬렉션 식별자입니다.

요청 본문

섹션 제목: “요청 본문”
필드타입필수기본값설명
querystring예*""텍스트 쿼리입니다. query 또는 queryVector 중 하나는 필요합니다.
queryVectornumber[]예*null원시 임베딩 벡터입니다.
topKinteger아니오10최대 결과 수입니다. 범위: 1–1000.
modelstring아니오null임베딩 모델 덮어쓰기값입니다.
filterobject아니오null메타데이터 필터입니다.
accessModestring아니오autoauto, internal, external 중 하나입니다. raw는 내부 전용입니다.
modestring아니오hybridvector 또는 hybrid입니다.
rerankboolean아니오false재정렬(re-ranking)을 활성화합니다.
rerankTopKinteger아니오null재정렬 대상 후보 수입니다.
minScorenumber아니오null최소 결과 점수입니다. 범위: 0–1.
debugboolean아니오false디버깅용 소요 시간과 점수를 포함합니다.

응답 예시

섹션 제목: “응답 예시”
{
  "bucket_id": "product-docs",
  "query": "migration",
  "search_id": "search_01J8X1234567890ABCDEF",
  "results": [
    {
      "id": "chunk_042",
      "score": 0.923,
      "text": "Migration guide excerpt...",
      "metadata": {"document_id": "doc_042"},
      "citation": null
    }
  ],
  "degraded": false,
  "warnings": []
}

오류

섹션 제목: “오류”
상태원인
400query 또는 queryVector가 누락되었거나, 시간 매개변수가 잘못되었습니다.
403raw 검색 모드는 내부 전용입니다.
404버킷 또는 컬렉션을 찾을 수 없습니다.

POST /v2/buckets/{bucket_id}/documents

섹션 제목: “POST /v2/buckets/{bucket_id}/documents”

하나 이상의 파일을 버킷에 업로드합니다. 업로드된 파일은 추출, 청크(chunk) 분할, 임베딩, 인덱싱을 거쳐 비동기로 처리됩니다. 이 엔드포인트는 multipart/form-data를 받습니다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
bucket_idstring예버킷 식별자입니다.

폼 필드

섹션 제목: “폼 필드”
필드타입필수기본값설명
filesfile예—하나 이상의 파일입니다. PDF, Markdown, 텍스트, Office 문서, 이미지를 지원합니다.
ocr_strategystring아니오auto이미지 기반 문서에 대한 OCR 전략입니다.
chunk_sizeinteger아니오512목표 청크 크기입니다. 범위: 64–8192.
chunk_overlapinteger아니오50청크 중첩 크기입니다. 범위: 0–512.
metadatastring아니오null업로드되는 모든 파일에 첨부할 JSON 문자열화 객체입니다.
collection_idstring아니오null대상 하위 컬렉션입니다. 기본값은 버킷입니다.

요청 예시

섹션 제목: “요청 예시”
Terminal window
curl -X POST ${API_BASE_URL}/v2/buckets/product-docs/documents \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "ocr_strategy=auto" \
  -F "chunk_size=512" \
  -F 'metadata={"source":"support","product":"schift"}'

응답 예시

섹션 제목: “응답 예시”
{
  "jobs": [
    {
      "job_id": "job_01J8X1234567890ABCDEF",
      "document_id": "doc_01J8X1234567890ABCDEF",
      "file_name": "manual.pdf",
      "file_type": "pdf",
      "status": "queued",
      "estimated_cost": 0.05
    }
  ],
  "total_estimated_cost": 0.05
}

오류

섹션 제목: “오류”
상태원인
400지원하지 않는 파일 형식이거나 잘못된 폼 데이터입니다.
403API 키에 buckets:manage 스코프가 없습니다.
404버킷을 찾을 수 없습니다.
413파일 또는 요청이 업로드 제한을 초과했습니다.

GET /v2/buckets/{bucket_id}/documents

섹션 제목: “GET /v2/buckets/{bucket_id}/documents”

버킷의 문서 목록을 조회합니다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
bucket_idstring예버킷 식별자입니다.

쿼리 매개변수

섹션 제목: “쿼리 매개변수”
매개변수타입필수기본값설명
statusstring아니오—문서 상태로 필터링합니다.
limitinteger아니오50최대 결과 수입니다. 범위: 1–500.

응답 예시

섹션 제목: “응답 예시”
[
  {
    "id": "doc_01J8X1234567890ABCDEF",
    "bucket_id": "product-docs",
    "collection_id": null,
    "file_name": "manual.pdf",
    "file_type": "pdf",
    "status": "ready",
    "metadata": {"source": "support", "product": "schift"},
    "source_metadata": {},
    "latest_job_id": "job_01J8X1234567890ABCDEF",
    "latest_successful_job_id": "job_01J8X1234567890ABCDEF",
    "last_error_summary": null,
    "created_at": "2026-06-19T04:00:00Z",
    "updated_at": "2026-06-19T04:05:00Z"
  }
]

오류

섹션 제목: “오류”
상태원인
404버킷을 찾을 수 없습니다.

GET /v2/buckets/{bucket_id}/documents/{document_id}

섹션 제목: “GET /v2/buckets/{bucket_id}/documents/{document_id}”

ID로 단일 문서를 조회합니다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
bucket_idstring예버킷 식별자입니다.
document_idstring예문서 식별자입니다.

응답 예시

섹션 제목: “응답 예시”

GET /v2/buckets/{bucket_id}/documents 응답의 단일 항목과 동일한 형식입니다.

오류

섹션 제목: “오류”
상태원인
404버킷 또는 문서를 찾을 수 없습니다.

PATCH /v2/buckets/{bucket_id}/documents/{document_id}

섹션 제목: “PATCH /v2/buckets/{bucket_id}/documents/{document_id}”

문서의 메타데이터를 업데이트합니다. 검색 노출에 영향을 주는 변경은 기본적으로 재인덱싱(reindex)을 트리거합니다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
bucket_idstring예버킷 식별자입니다.
document_idstring예문서 식별자입니다.

요청 본문

섹션 제목: “요청 본문”
필드타입필수기본값설명
metadataobject아니오{}병합할 메타데이터입니다.
public_accessibleboolean아니오null문서를 공개 접근 가능하게 할지 여부입니다.
privacy_levelinteger아니오null프라이버시 수준입니다. 범위: 1–10.
classificationstring아니오nullinternal, public, restricted, confidential 중 하나입니다.
review_statusstring아니오nullpending, approved, rejected 중 하나입니다.
reindexboolean아니오true업데이트 후 재인덱싱을 큐에 넣습니다.

응답 예시

섹션 제목: “응답 예시”

GET /v2/buckets/{bucket_id}/documents/{document_id} 응답과 동일한 형식입니다.

오류

섹션 제목: “오류”
상태원인
400잘못된 메타데이터입니다.
404버킷 또는 문서를 찾을 수 없습니다.

DELETE /v2/buckets/{bucket_id}/documents/{document_id}

섹션 제목: “DELETE /v2/buckets/{bucket_id}/documents/{document_id}”

문서의 영구 삭제를 큐에 넣습니다. 삭제는 비동기로 수행되며 작업 ID(job ID)를 반환합니다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
bucket_idstring예버킷 식별자입니다.
document_idstring예문서 식별자입니다.

응답 예시

섹션 제목: “응답 예시”
{
  "bucket_id": "product-docs",
  "document_id": "doc_01J8X1234567890ABCDEF",
  "job_id": "job_01J8Y1234567890ABCDEF",
  "status": "queued",
  "delete_requested_at": "2026-06-19T05:10:00Z"
}

오류

섹션 제목: “오류”
상태원인
404버킷 또는 문서를 찾을 수 없습니다.

GET /v2/buckets/{bucket_id}/metadata-keys

섹션 제목: “GET /v2/buckets/{bucket_id}/metadata-keys”

버킷 내 문서에 나타나는 메타데이터 키와 각 키의 가장 흔한 값들을 조회합니다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
bucket_idstring예버킷 식별자입니다.

쿼리 매개변수

섹션 제목: “쿼리 매개변수”
매개변수타입필수기본값설명
limitinteger아니오500키를 수집할 때 스캔할 최대 문서 수입니다. 범위: 1–2000.
values_per_keyinteger아니오20키당 반환할 최대 값 수입니다. 범위: 0–100.

응답 예시

섹션 제목: “응답 예시”
{
  "bucket_id": "product-docs",
  "keys": [
    {
      "key": "product",
      "document_count": 12,
      "values": [
        {"value": "schift", "count": 10},
        {"value": "docs", "count": 2}
      ]
    }
  ]
}

오류

섹션 제목: “오류”
상태원인
404버킷을 찾을 수 없습니다.

GET /v2/buckets/{bucket_id}/metadata-keys/{key}/values

섹션 제목: “GET /v2/buckets/{bucket_id}/metadata-keys/{key}/values”

특정 메타데이터 키에 대해 관찰된 값 목록을 조회합니다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
bucket_idstring예버킷 식별자입니다.
keystring예메타데이터 키입니다.

쿼리 매개변수

섹션 제목: “쿼리 매개변수”
매개변수타입필수기본값설명
limitinteger아니오100최대 고유 값 수입니다. 범위: 1–1000.
document_limitinteger아니오2000스캔할 최대 문서 수입니다. 범위: 1–10000.

응답 예시

섹션 제목: “응답 예시”
{
  "bucket_id": "product-docs",
  "key": "product",
  "values": [
    {"value": "schift", "count": 10},
    {"value": "docs", "count": 2}
  ]
}

오류

섹션 제목: “오류”
상태원인
404버킷을 찾을 수 없거나 메타데이터 키를 찾을 수 없습니다.

참고 항목

섹션 제목: “참고 항목”