Knowledge API
Knowledge는 D.Hub에서 문서 기반 지식을 관리하는 상위 컨테이너입니다. 각 Knowledge는 여러 Document를 하위 리소스로 포함하며, Manager API를 통해 CRUD 작업을 수행합니다.
Base URL
모든 엔드포인트는 Manager API의 /api/v1/knowledges 경로 하위에 있습니다.
엔드포인트 요약
Knowledge
| Method | Path | Description |
|---|---|---|
| POST | /knowledges/ | Knowledge 생성 |
| GET | /knowledges/ | Knowledge 목록 조회 |
| GET | /knowledges/{knowledge_id} | Knowledge 상세 조회 |
| GET | /knowledges/{knowledge_id}/versions | 버전 이력 조회 |
| PUT | /knowledges/{knowledge_id} | Knowledge 업데이트 |
| DELETE | /knowledges/{knowledge_id} | Knowledge 삭제 |
Document (하위 리소스)
| Method | Path | Description |
|---|---|---|
| POST | /knowledges/{kid}/documents/ | 문서 생성 |
| GET | /knowledges/{kid}/documents/ | 문서 목록 조회 |
| GET | /knowledges/{kid}/documents/{did} | 문서 상세 조회 |
| GET | /knowledges/{kid}/documents/{did}/versions | 문서 버전 이력 |
| PUT | /knowledges/{kid}/documents/{did} | 문서 업데이트 |
| DELETE | /knowledges/{kid}/documents/{did} | 문서 삭제 |
Knowledge 엔드포인트
POST /knowledges/
새로운 Knowledge를 생성합니다.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Knowledge 이름 |
alias | string | No | 별칭 |
type | string | No | Knowledge 유형 |
groups | array[string] | No | 그룹 목록 |
tags | array[string] | No | 태그 목록 |
options | object | No | 추가 옵션 (임베딩 모델 등) |
Response
200 OK
{
"item": "knowledge-abc123"
}
GET /knowledges/
Knowledge 목록을 조회합니다.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 100 | 최대 조회 개수 |
token | string | - | 페이지네이션 토큰 |
groups | string | - | 그룹 필터 (쉼표로 구분) |
Response
200 OK
{
"items": {
"knowledge-abc123": "{\"id\":\"knowledge-abc123\",\"name\":\"Product FAQ\", ...}"
},
"token": "next-page-token"
}
GET /knowledges/{knowledge_id}
특정 Knowledge의 상세 정보를 조회합니다.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
knowledge_version | string | No | 특정 버전 조회 |
Response
200 OK
{
"id": "knowledge-abc123",
"name": "Product FAQ",
"alias": "product-faq",
"category": "knowledge",
"type": "document",
"groups": ["support"],
"tags": ["faq", "product"],
"options": {
"embedding": "BAAI/bge-m3"
},
"comment": "",
"created_at": 1700000000,
"updated_at": 1700100000
}
GET /knowledges/{knowledge_id}/versions
Knowledge의 버전 이력을 조회합니다.
Response
200 OK
[
{
"version_id": "v2",
"last_modified": "2024-06-15T10:30:00Z",
"size": 1024
}
]
PUT /knowledges/{knowledge_id}
Knowledge 메타데이터를 수정합니다. 전달된 필드만 업데이트됩니다.
Request Body
| Field | Type | Description |
|---|---|---|
name | string | Knowledge 이름 |
alias | string | 별칭 |
type | string | Knowledge 유형 |
groups | array[string] | 그룹 목록 |
tags | array[string] | 태그 목록 |
options | object | 추가 옵션 |
comment | string | 버전 코멘트 |
Response
200 OK
{
"message": "Knowledge updated successfully"
}
DELETE /knowledges/{knowledge_id}
Knowledge를 삭제합니다.
경고
하위 Document가 남아있으면 409 Conflict 에러가 반환됩니다. 먼저 모든 Document를 삭제한 후 Knowledge를 삭제하세요.
Response
200 OK
{
"message": "Knowledge deleted successfully"
}
Document 엔드포인트
Document는 Knowledge 하위의 개별 문서 단위입니다. 웹 크롤링 결과, 업로드된 파일, 수동 작성 문서 등 다양한 유형을 지원합니다.
POST /knowledges/{kid}/documents/
Knowledge에 새로운 Document를 생성합니다.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | 문서 이름 |
alias | string | No | 별칭 |
type | string | No | 문서 유형 (WEB, FILE, MANUAL) |
groups | array[string] | No | 그룹 목록 |
tags | array[string] | No | 태그 목록 |
options | object | No | 추가 옵션 (URL, 파일명 등) |
Response
200 OK
{
"item": "knowledge.document-xyz789"
}
DELETE /knowledges/{kid}/documents/{did}
Document를 삭제합니다. FILE 타입의 경우 S3에 저장된 원본 파일도 함께 삭제됩니다.
Response
200 OK
{
"message": "Document deleted successfully"
}
사용 예시
cURL
# Knowledge 생성
curl -X POST https://api.dhub.io/api/v1/knowledges/ \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Product FAQ",
"type": "document",
"groups": ["support"],
"tags": ["faq"],
"options": {"embedding": "BAAI/bge-m3"}
}'
# Knowledge 목록 조회
curl https://api.dhub.io/api/v1/knowledges/?limit=50 \
-H "Authorization: Bearer <access_token>"
# Document 생성
curl -X POST https://api.dhub.io/api/v1/knowledges/knowledge-abc123/documents/ \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Getting Started Guide",
"type": "WEB",
"options": {"url": "https://docs.example.com/guide"}
}'
# Knowledge 삭제
curl -X DELETE https://api.dhub.io/api/v1/knowledges/knowledge-abc123 \
-H "Authorization: Bearer <access_token>"
Knowledge Builder 연동
Knowledge와 Document를 생성한 후, Knowledge Builder API를 사용하여 문서 인덱싱과 청크 관리를 수행합니다. 검색 및 RAG Chat은 Knowledge Chat API를 참조하세요.