본문으로 건너뛰기
버전: Next

Knowledge API

Knowledge는 D.Hub에서 문서 기반 지식을 관리하는 상위 컨테이너입니다. 각 Knowledge는 여러 Document를 하위 리소스로 포함하며, Manager API를 통해 CRUD 작업을 수행합니다.

Base URL

모든 엔드포인트는 Manager API의 /api/v1/knowledges 경로 하위에 있습니다.

엔드포인트 요약​

Knowledge​

MethodPathDescription
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 (하위 리소스)​

MethodPathDescription
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​

FieldTypeRequiredDescription
namestringYesKnowledge 이름
aliasstringNo별칭
typestringNoKnowledge 유형
groupsarray[string]No그룹 목록
tagsarray[string]No태그 목록
optionsobjectNo추가 옵션 (임베딩 모델 등)

Response​

200 OK

{
  "item": "knowledge-abc123"
}

GET /knowledges/​

Knowledge 목록을 조회합니다.

Query Parameters​

ParameterTypeDefaultDescription
limitinteger100최대 조회 개수
tokenstring-페이지네이션 토큰
groupsstring-그룹 필터 (쉼표로 구분)

Response​

200 OK

{
  "items": {
    "knowledge-abc123": "{\"id\":\"knowledge-abc123\",\"name\":\"Product FAQ\", ...}"
  },
  "token": "next-page-token"
}

GET /knowledges/{knowledge_id}​

특정 Knowledge의 상세 정보를 조회합니다.

Query Parameters​

ParameterTypeRequiredDescription
knowledge_versionstringNo특정 버전 조회

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​

FieldTypeDescription
namestringKnowledge 이름
aliasstring별칭
typestringKnowledge 유형
groupsarray[string]그룹 목록
tagsarray[string]태그 목록
optionsobject추가 옵션
commentstring버전 코멘트

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​

FieldTypeRequiredDescription
namestringYes문서 이름
aliasstringNo별칭
typestringNo문서 유형 (WEB, FILE, MANUAL)
groupsarray[string]No그룹 목록
tagsarray[string]No태그 목록
optionsobjectNo추가 옵션 (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를 참조하세요.