콘텐츠로 이동
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 "files=@manual.pdf" \
  -F "files=@release-notes.md" \
  -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버킷을 찾을 수 없거나 메타데이터 키를 찾을 수 없는다.

참고 항목

섹션 제목: “참고 항목”