컬렉션

Show: All versions v2 only

Collections API는 구형 클라이언트와 SDK를 위한 v1 호환성 계층(compatibility surface)이며, 더 이상 사용되지 않는(deprecated) API입니다. 내부적으로 collection(컬렉션)과 bucket(버킷)은 동일한 기본 저장 객체를 가리키며, 컬렉션 검색은 버킷 검색에 위임됩니다.

참고: 새로운 연동에서는 이 문서의 경로 대신 Buckets와 POST /v2/buckets/\{bucket_id\}/search를 사용하세요.

API 버전

버전	상태	경로 접두어	안내
v1	폐기 예정	/v1/collections/*	호환용입니다. 새로운 기능이 추가되지 않습니다.
v2	현재	/v2/buckets/*	모든 신규 연동에 사용하세요.

v1 컬렉션 검색 엔드포인트는 Deprecation: true, Warning, 그리고 POST /v2/buckets/\{bucket_id\}/search를 가리키는 Link 후속 버전 헤더를 반환합니다.

인증

모든 컬렉션 API 엔드포인트는 Authorization 헤더에 API 키가 필요합니다.

Authorization: Bearer sch_xxxxxxxxxxxxxxxxxxxx

각 엔드포인트는 특정 API 키 스코프(scope)도 필요합니다.

Scope	Access
collections:manage	컬렉션을 생성하고 삭제합니다.
collections:read	컬렉션을 목록 조회하거나, 단일 조회하거나, 통계를 읽습니다.
collections:use	벡터를 추가(upsert)하거나 삭제합니다.
embed	문서를 임베딩하고 추가합니다(/documents 및 /add).
query	컬렉션을 검색합니다.

/v1/organizations/\{org_id\} 아래의 대시보드 세션 경로는 대상 조직(organization)의 멤버인 로그인한 사용자가 필요합니다.

컬렉션 객체

필드	타입	설명
id	string	고유한 컬렉션 식별자입니다.
name	string	사람이 읽을 수 있는 컬렉션 이름입니다.
dimension	integer	컬렉션의 임베딩 차원입니다.
model	string	컬렉션에 사용되는 임베딩 모델입니다.
backend	string	벡터 백엔드입니다. 예: engine.
vector_count	integer	색인된 벡터의 개수입니다.

POST /v1/collections

새 컬렉션을 생성합니다. 컬렉션 이름은 조직 내에서 고유해야 합니다.

요청 본문

필드	타입	필수	기본값	설명
name	string	Yes	—	컬렉션 이름입니다.
dimension	integer	Yes	—	컬렉션의 벡터 차원입니다.
model	string	No	schift-embed-1-small	사용할 임베딩 모델입니다.
backend	string	No	engine	벡터 백엔드입니다. 지원 값: engine, pgvector, weaviate, qdrant, pinecone, milvus, chroma, elasticsearch, redis, mongodb.

요청 예시

{
  "name": "legacy-faq",
  "dimension": 1024,
  "model": "schift-embed-1-small",
  "backend": "engine"
}

응답 예시

{
  "id": "abc123def456",
  "name": "legacy-faq",
  "dimension": 1024,
  "model": "schift-embed-1-small",
  "backend": "engine",
  "vector_count": 0
}

오류

상태	원인
400	잘못된 백엔드 또는 요청 본문입니다.
403	API 키에 collections:manage 스코프가 없습니다.
409	동일한 이름의 컬렉션이 이미 존재합니다.

GET /v1/collections

인증된 조직의 컬렉션을 목록 조회합니다.

응답 예시

[
  {
    "id": "abc123def456",
    "name": "legacy-faq",
    "dimension": 1024,
    "model": "schift-embed-1-small",
    "backend": "engine",
    "vector_count": 128
  }
]

오류

상태	원인
403	API 키에 collections:read 스코프가 없습니다.

GET /v1/collections/{name}

이름으로 단일 컬렉션을 조회합니다.

경로 매개변수

Parameter	Type	Description
name	string	컬렉션 이름입니다.

응답 예시

{
  "id": "abc123def456",
  "name": "legacy-faq",
  "dimension": 1024,
  "model": "schift-embed-1-small",
  "backend": "engine",
  "vector_count": 128
}

오류

상태	원인
403	API 키에 collections:read 스코프가 없습니다.
404	컬렉션을 찾을 수 없습니다.

GET /v1/collections/{name}/stats

컬렉션의 현재 벡터 개수와 메타데이터를 반환합니다. 개수는 벡터 백엔드에서 직접 읽어오며, 저장된 개수도 갱신됩니다.

경로 매개변수

Parameter	Type	Description
name	string	컬렉션 이름입니다.

응답 예시

{
  "name": "legacy-faq",
  "dimension": 1024,
  "model": "schift-embed-1-small",
  "backend": "engine",
  "vector_count": 128
}

오류

상태	원인
403	API 키에 collections:read 스코프가 없습니다.
404	컬렉션을 찾을 수 없습니다.

DELETE /v1/collections/{name}

컬렉션을 삭제하고 벡터 테이블을 제거합니다.

경로 매개변수

Parameter	Type	Description
name	string	컬렉션 이름입니다.

응답

성공 시 204 No Content를 반환합니다.

오류

상태	원인
403	API 키에 collections:manage 스코프가 없습니다.
404	컬렉션을 찾을 수 없습니다.

POST /v1/collections/{collection}/vectors

컬렉션에 원시 벡터를 추가(upsert)합니다. 이미 존재하는 벡터 id는 대첩니다.

참고: 요청당 최대 배치 크기는 2048개 벡터입니다.

경로 매개변수

Parameter	Type	Description
collection	string	컬렉션 이름입니다.

요청 본문

필드	타입	필수	설명
vectors	object[]	Yes	벡터 항목 배열입니다.
vectors[].id	string	Yes	고유한 벡터 식별자입니다.
vectors[].values	number[]	Yes	임베딩 값입니다. 컬렉션 차원과 일치해야 합니다.
vectors[].metadata	object	No	자유 형식의 메타데이터입니다.

요청 예시

{
  "vectors": [
    {
      "id": "vec-1",
      "values": [0.01, -0.02, 0.03],
      "metadata": {"source": "faq"}
    }
  ]
}

응답 예시

{
  "upserted": 1
}

오류

상태	원인
400	배치 크기가 2048을 초과하거나, 벡터 차원이 컬렉션과 일치하지 않습니다.
402	할당량을 초과했습니다.
403	API 키에 collections:use 스코프가 없습니다.
404	컬렉션을 찾을 수 없습니다.

DELETE /v1/collections/{collection}/vectors

ID로 컬렉션에서 특정 벡터를 삭제합니다.

경로 매개변수

Parameter	Type	Description
collection	string	컬렉션 이름입니다.

요청 본문

필드	타입	필수	설명
ids	string[]	Yes	삭제할 벡터 ID입니다. 비어 있으면 안 됩니다.

요청 예시

{
  "ids": ["vec-1", "vec-2"]
}

응답 예시

{
  "deleted": 2
}

오류

상태	원인
400	ids가 비어 있습니다.
403	API 키에 collections:use 스코프가 없습니다.
404	컬렉션을 찾을 수 없습니다.
501	설정된 백엔드가 ID 기반 벡터 삭제를 지원하지 않습니다.

POST /v1/collections/{collection}/documents

문서를 임베딩하고 그 결과 벡터를 컬렉션에 저장합니다. 요청 본문에는 대상 임베딩 모델이 포함됩니다.

참고: 요청당 최대 배치 크기는 2048개 문서입니다.

경로 매개변수

Parameter	Type	Description
collection	string	컬렉션 이름입니다.

요청 본문

필드	타입	필수	설명
documents	object[]	Yes	문서 항목 배열입니다.
documents[].id	string	No	문서 식별자입니다. 생략하면 자동 생성됩니다.
documents[].text	string	Yes	임베딩할 텍스트입니다.
documents[].metadata	object	No	자유 형식의 메타데이터입니다.
model	string	Yes	임베딩 모델 ID입니다.

요청 예시

{
  "documents": [
    {
      "id": "doc-1",
      "text": "How do I reset my password?",
      "metadata": {"category": "support"}
    }
  ],
  "model": "schift-embed-1-small"
}

응답 예시

{
  "upserted": 1
}

오류

상태	원인
400	배치 크기가 2048을 초과하거나, 임베딩 모델을 알 수 없습니다.
402	할당량을 초과했습니다.
403	API 키에 필요한 collections:use 또는 embed 스코프가 없습니다.
404	컬렉션을 찾을 수 없습니다.

POST /v1/collections/{name}/add

문서를 임베딩하여 컬렉션에 추가합니다. 컬렉션이 존재하지 않으면 dimension=1024, model=schift-embed-1-small, backend=engine으로 자동 생성됩니다.

참고: 요청당 최대 배치 크기는 2048개 문서입니다.

경로 매개변수

Parameter	Type	Description
name	string	컬렉션 이름입니다.

요청 본문

필드	타입	필수	기본값	설명
documents	string[]	Yes	—	임베딩할 원시 텍스트 문자열입니다. 비어 있으면 안 됩니다.
ids	string[]	No	null	선택적 문서 ID입니다.
metadata	object[]	No	null	선택적 메타데이터 객체로, 문서당 하나씩입니다.
task	string	No	null	임베딩 태스크입니다. 다음 중 하나: retrieval_query, retrieval_document, semantic_similarity, question_answering, clustering, classification, code_retrieval.
model	string	No	schift-embed-1-small	임베딩 모델 ID입니다.

요청 예시

{
  "documents": [
    "How do I reset my password?",
    "Where can I download invoices?"
  ],
  "metadata": [
    {"category": "support"},
    {"category": "billing"}
  ],
  "model": "schift-embed-1-small"
}

응답 예시

{
  "collection": "legacy-faq",
  "added": 2,
  "ids": ["id-1", "id-2"]
}

오류

상태	원인
400	documents가 비어 있거나 배치 크기가 2048을 초과합니다.
402	할당량을 초과했습니다.
403	임베딩 사용 한도에 도달했거나, API 키에 필요한 스코프가 없습니다.

POST /v1/collections/{name}/search

컬렉션을 검색합니다. 이 엔드포인트는 bucket search 위에 있는 호환성 래퍼이며, 단순화된 응답을 반환합니다.

경로 매개변수

Parameter	Type	Description
name	string	컬렉션 이름입니다.

요청 본문

필드	타입	필수	기본값	설명
query	string	No*	—	텍스트 쿼리입니다. query 또는 query_vector 중 하나는 필수입니다.
query_vector	number[]	No*	—	미리 계산된 쿼리 벡터입니다.
task	string	No	null	임베딩 태스크입니다. 유효한 태스크 값을 참조하세요.
top_k	integer	No	10	반환할 결과 개수입니다. 최대 1000.
filter	object	No	null	메타데이터 필터입니다.
model	string	No	null	임베딩 또는 재정렬 모델 오버라이드입니다.
mode	string	No	hybrid	검색 모드입니다. vector 또는 hybrid.
rerank	boolean	No	false	재정렬을 활성화합니다.
rerank_top_k	integer	No	null	재정렬의 상위 k 컷오프입니다.
rerank_model	string	No	null	재정렬 모델 ID입니다.
temporal	string	No	null	시간 필터입니다. before, after, between, as_of, 또는 latest.
temporal_start	integer	No	null	temporal이 설정된 경우 필요합니다(latest 제외).
temporal_end	integer	No	null	temporal=between인 경우 필요합니다.
advanced	object	No	null	고급 스코어링 파라미터입니다. graph_weight, temporal_weight, hit_weight, vector_weight, bm25_weight, hops, temporal_half_life_days.
expand_context	object	No	null	컨텍스트 확장 파라미터입니다. window, max_extra, score_decay.

요청 예시

{
  "query": "reset password",
  "top_k": 5,
  "filter": {"category": "support"},
  "mode": "hybrid"
}

응답 예시

{
  "collection": "legacy-faq",
  "results": [
    {
      "id": "doc-1",
      "score": 0.92,
      "text": "How do I reset my password?",
      "metadata": {"category": "support"},
      "neighbors": null,
      "citation": null
    }
  ]
}

응답에는 v2 bucket search 후속 엔드포인트를 가리키는 더 이상 사용되지 않음(deprecation) 헤더도 포함됩니다.

Deprecation: true
Warning: 299 - "Deprecated search endpoint; migrate to /v2/buckets/{bucket_id}/search"
Link: </v2/buckets/abc123def456/search>; rel="successor-version"

오류

상태	원인
400	query와 query_vector 둘 다 제공되지 않았거나, 잘못된 시간 매개변수입니다.
402	할당량을 초과했습니다.
403	검색 사용 한도에 도달했거나, API 키에 필요한 스코프가 없습니다.
404	컬렉션을 찾을 수 없습니다.

대시보드 조직 경로

이 경로는 Schift 대시보드에서 사용되며 세션 인증에 의존합니다. 호출하는 사용자는 \{org_id\}의 멤버여야 합니다.

GET /v1/organizations/{org_id}/collections

조직의 컬렉션을 목록 조회합니다.

GET /v1/organizations/{org_id}/collections/{name}

조직에서 단일 컬렉션을 조회합니다.

POST /v1/organizations/{org_id}/collections

조직에 컬렉션을 생성합니다.

요청 본문

필드	타입	필수	기본값	설명
name	string	Yes	—	컬렉션 이름입니다.
model	string	No	schift-embed-1-small	임베딩 모델입니다.
dimension	integer	No	model default or 1024	벡터 차원입니다.
backend	string	No	engine	벡터 백엔드입니다.

오류

상태	원인
400	name이 누락되었거나 지원하지 않는 백엔드입니다.
403	사용자가 조직 멤버가 아니거나, 요금제의 컬렉션 한도에 도달했습니다.

DELETE /v1/organizations/{org_id}/collections/{name}

조직에서 컬렉션을 삭제합니다. 204 No Content를 반환합니다.

GET /v1/organizations/{org_id}/collections/{name}/stats

실시간 벡터 개수를 포함한 컬렉션 통계를 반환합니다.

GET /v1/organizations/{org_id}/vectordb-configs

조직 수준의 VectorDB 설정을 목록 조회합니다.

PUT /v1/organizations/{org_id}/vectordb-configs

백엔드의 VectorDB 설정을 생성하거나 업데이트합니다.

요청 본문

필드	타입	필수	설명
collection_id	string	Yes	대상 컬렉션 ID입니다.
backend	string	Yes	백엔드 이름입니다. 지원되는 값이어야 합니다.
endpoint	string	No	백엔드 엔드포인트 URL입니다.
api_key	string	No	백엔드 인증 정보입니다.
extra	object	No	추가적인 백엔드별 옵션입니다.

응답 예시

{
  "status": "ok"
}

오류

상태	원인
400	지원하지 않는 백엔드입니다.
403	사용자가 조직 멤버가 아닙니다.

같이 보기

• Buckets
• Query
• Embeddings