Knowledge API

Knowledge is a top-level container for managing document-based knowledge in D.Hub. Each Knowledge contains multiple Documents as sub-resources, and CRUD operations are performed through the Manager API.

Base URL

All endpoints are under the Manager API's /api/v1/knowledges path.

Endpoint Summary

Knowledge

Method	Path	Description
POST	/knowledges/	Create a Knowledge
GET	/knowledges/	List Knowledges
GET	/knowledges/{knowledge_id}	Get Knowledge details
GET	/knowledges/{knowledge_id}/versions	Get version history
PUT	/knowledges/{knowledge_id}	Update a Knowledge
DELETE	/knowledges/{knowledge_id}	Delete a Knowledge

Document (Sub-Resource)

Method	Path	Description
POST	/knowledges/{kid}/documents/	Create a document
GET	/knowledges/{kid}/documents/	List documents
GET	/knowledges/{kid}/documents/{did}	Get document details
GET	/knowledges/{kid}/documents/{did}/versions	Document version history
PUT	/knowledges/{kid}/documents/{did}	Update a document
DELETE	/knowledges/{kid}/documents/{did}	Delete a document

---

Knowledge Endpoints

POST /knowledges/

Creates a new Knowledge.

Request Body

Field	Type	Required	Description
name	string	Yes	Knowledge name
alias	string	No	Alias
type	string	No	Knowledge type
groups	array[string]	No	Group list
tags	array[string]	No	Tag list
options	object	No	Additional options (embedding model, etc.)

Response

200 OK

{
  "item": "knowledge-abc123"
}

---

GET /knowledges/

Retrieves a list of Knowledges.

Query Parameters

Parameter	Type	Default	Description
limit	integer	100	Maximum number of items to retrieve
token	string	-	Pagination token
groups	string	-	Group filter (comma-separated)

Response

200 OK

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

---

GET /knowledges/{knowledge_id}

Retrieves detailed information of a specific Knowledge.

Query Parameters

Parameter	Type	Required	Description
knowledge_version	string	No	Retrieve a specific version

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

Retrieves the version history of a Knowledge.

Response

200 OK

[
  {
    "version_id": "v2",
    "last_modified": "2024-06-15T10:30:00Z",
    "size": 1024
  }
]

---

PUT /knowledges/{knowledge_id}

Updates Knowledge metadata. Only the provided fields are updated.

Request Body

Field	Type	Description
name	string	Knowledge name
alias	string	Alias
type	string	Knowledge type
groups	array[string]	Group list
tags	array[string]	Tag list
options	object	Additional options
comment	string	Version comment

Response

200 OK

{
  "message": "Knowledge updated successfully"
}

---

DELETE /knowledges/{knowledge_id}

Deletes a Knowledge.

warning

If sub-Documents remain, a 409 Conflict error is returned. Delete all Documents first before deleting the Knowledge.

Response

200 OK

{
  "message": "Knowledge deleted successfully"
}

---

Document Endpoints

Documents are individual document units under a Knowledge. They support various types including web crawling results, uploaded files, and manually written documents.

POST /knowledges/{kid}/documents/

Creates a new Document under a Knowledge.

Request Body

Field	Type	Required	Description
name	string	Yes	Document name
alias	string	No	Alias
type	string	No	Document type (WEB, FILE, MANUAL)
groups	array[string]	No	Group list
tags	array[string]	No	Tag list
options	object	No	Additional options (URL, filename, etc.)

Response

200 OK

{
  "item": "knowledge.document-xyz789"
}

---

DELETE /knowledges/{kid}/documents/{did}

Deletes a Document. For FILE type documents, the original file stored in S3 is also deleted.

Response

200 OK

{
  "message": "Document deleted successfully"
}

---

Usage Examples

cURL

# Create a 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"}
  }'

# List Knowledges
curl https://api.dhub.io/api/v1/knowledges/?limit=50 \
  -H "Authorization: Bearer <access_token>"

# Create a 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"}
  }'

# Delete a Knowledge
curl -X DELETE https://api.dhub.io/api/v1/knowledges/knowledge-abc123 \
  -H "Authorization: Bearer <access_token>"

Knowledge Builder Integration

After creating Knowledge and Documents, use the Knowledge Builder API to perform document indexing and chunk management. For search and RAG Chat, refer to the Knowledge Chat API.