Knowledgebase API
The Knowledgebase API allows you to programmatically manage knowledgebase items including webpages, documents, and Q&A references. These knowledge sources are used by your AI agents to provide accurate responses.
Rate Limits & Pricing
- Get/Update Operations: 100 requests per hour
- Search (Dhyan Knowledge): 10,000 queries per hour — 1 credit per search
- Webpage Refresh: Once per 24 hours per webpage
Table of Contents
Knowledgebase
Webpages
Documents
Q&A References
Access via Agent ID
/api/v1/knowledgebase/:knowledgebaseIdGet a knowledgebase with all its items (webpages, documents, and references)
Path Parameters
knowledgebaseIdstringrequiredThe unique identifier (UUID) of the knowledgebase
Responses
{
"data": {
"id": "kb-uuid-1234",
"name": "Customer Support KB",
"description": "Knowledge base for support agents",
"webpages": [
{
"id": "webpage-uuid-1",
"url": "https://example.com/faq",
"name": "FAQ Page",
"notes": "Main FAQ content",
"lastScrapedAt": "2024-01-15T10:00:00.000Z",
"isUpdating": false
}
],
"documents": [
{
"id": "doc-uuid-1",
"fileName": "product-manual.pdf",
"name": "Product Manual",
"notes": "Complete product documentation",
"isUpdating": false
}
],
"references": [
{
"id": "ref-uuid-1",
"question": "What are your business hours?",
"answer": "We are open Monday to Friday, 9 AM to 5 PM EST.",
"type": "QA"
}
]
}
}{
"error": "Knowledgebase not found"
}API Tester
/api/v1/knowledgebase/:knowledgebaseId/searchSearch the knowledgebase using our Dhyan Knowledge engine. Each search query costs 1 credit.
Path Parameters
knowledgebaseIdstringrequiredThe unique identifier (UUID) of the knowledgebase
Query Parameters
querystringrequiredThe search query (max 2000 characters). This will be semantically matched against your knowledgebase content.
limitinteger(default: 10)Maximum number of results to return (max 50)
thresholdnumber(default: 0.1)Minimum similarity threshold (0-1). Higher values return more relevant but fewer results.
Responses
{
"data": [
{
"id": "ref-uuid-1",
"question": "What are your business hours?",
"answer": "We are open Monday to Friday, 9 AM to 5 PM EST. On weekends, we offer limited support from 10 AM to 2 PM.",
"similarity": 0.892,
"type": "QA",
"source": "manual"
},
{
"id": "ref-uuid-2",
"question": "When is customer support available?",
"answer": "Our customer support team is available during business hours. For urgent matters, you can use our 24/7 chat bot.",
"similarity": 0.756,
"type": "QA",
"source": "webpage"
}
],
"meta": {
"query": "What time are you open?",
"resultCount": 2,
"limit": 10,
"threshold": 0.1,
"creditsUsed": 1
}
}{
"error": "Validation error",
"details": [
{
"field": "query",
"message": "Query is required"
}
]
}{
"error": "Knowledgebase not found"
}API Tester
Webpages
/api/v1/knowledgebase/:knowledgebaseId/webpages/:webpageIdGet a specific webpage with its extracted content
Path Parameters
knowledgebaseIdstringrequiredThe unique identifier of the knowledgebase
webpageIdstringrequiredThe unique identifier of the webpage
Responses
{
"data": {
"id": "webpage-uuid-1",
"url": "https://example.com/faq",
"name": "FAQ Page",
"notes": "Main FAQ content",
"lastScrapedAt": "2024-01-15T10:00:00.000Z",
"isUpdating": false,
"extractedContent": [
{
"id": "ref-uuid-1",
"question": "What is your return policy?",
"answer": "You can return items within 30 days..."
}
]
}
}API Tester
/api/v1/knowledgebase/:knowledgebaseId/webpages/:webpageIdUpdate webpage metadata (name, URL, notes)
Path Parameters
knowledgebaseIdstringrequiredThe unique identifier of the knowledgebase
webpageIdstringrequiredThe unique identifier of the webpage
Request Body
namestringDisplay name for the webpage (max 255 characters)
urlstringThe URL of the webpage
notesstringOptional notes about this webpage (max 5000 characters)
Responses
{
"data": {
"id": "webpage-uuid-1",
"url": "https://example.com/new-faq",
"name": "Updated FAQ Page",
"notes": "Updated notes",
"lastScrapedAt": "2024-01-15T10:00:00.000Z",
"isUpdating": false
},
"message": "Webpage updated successfully"
}API Tester
/api/v1/knowledgebase/:knowledgebaseId/webpages/:webpageId/refreshRe-scrape and update the content of a webpage. Limited to once per 24 hours per webpage.
Path Parameters
knowledgebaseIdstringrequiredThe unique identifier of the knowledgebase
webpageIdstringrequiredThe unique identifier of the webpage
Responses
{
"data": {
"id": "webpage-uuid-1",
"url": "https://example.com/faq",
"name": "FAQ Page",
"status": "refreshing"
},
"message": "Webpage refresh has been queued. The content will be updated shortly."
}{
"error": "Webpage is already being refreshed"
}{
"error": "Rate limit exceeded. Webpages can only be refreshed once per day.",
"nextAvailableAt": "2024-01-16T10:00:00.000Z"
}API Tester
Documents
/api/v1/knowledgebase/:knowledgebaseId/documents/:documentIdGet a specific document with its extracted content
Path Parameters
knowledgebaseIdstringrequiredThe unique identifier of the knowledgebase
documentIdstringrequiredThe unique identifier of the document
Responses
{
"data": {
"id": "doc-uuid-1",
"fileName": "product-manual.pdf",
"name": "Product Manual",
"notes": "Complete product documentation",
"isUpdating": false,
"extractedContent": [
{
"id": "ref-uuid-1",
"question": "How to install the product?",
"answer": "Follow these installation steps..."
}
]
}
}API Tester
/api/v1/knowledgebase/:knowledgebaseId/documents/:documentIdUpdate document metadata (name, notes)
Path Parameters
knowledgebaseIdstringrequiredThe unique identifier of the knowledgebase
documentIdstringrequiredThe unique identifier of the document
Request Body
namestringDisplay name for the document (max 255 characters)
notesstringOptional notes about this document (max 5000 characters)
Responses
{
"data": {
"id": "doc-uuid-1",
"fileName": "product-manual.pdf",
"name": "Updated Product Manual",
"notes": "Updated notes",
"isUpdating": false
},
"message": "Document updated successfully"
}API Tester
Q&A References
/api/v1/knowledgebase/:knowledgebaseId/references/:referenceIdGet a specific Q&A reference
Path Parameters
knowledgebaseIdstringrequiredThe unique identifier of the knowledgebase
referenceIdstringrequiredThe unique identifier of the reference
Responses
{
"data": {
"id": "ref-uuid-1",
"question": "What are your business hours?",
"answer": "We are open Monday to Friday, 9 AM to 5 PM EST.",
"type": "QA"
}
}API Tester
/api/v1/knowledgebase/:knowledgebaseId/references/:referenceIdUpdate a Q&A reference. The embedding will be automatically regenerated if the question or answer changes.
Path Parameters
knowledgebaseIdstringrequiredThe unique identifier of the knowledgebase
referenceIdstringrequiredThe unique identifier of the reference
Request Body
questionstringThe question that this reference answers (max 5000 characters)
answerstringThe answer to the question (max 50000 characters)
Responses
{
"data": {
"id": "ref-uuid-1",
"question": "What are your updated business hours?",
"answer": "We are now open Monday to Saturday, 8 AM to 6 PM EST.",
"type": "QA"
},
"message": "Reference updated successfully"
}API Tester
Access via Agent ID
All knowledgebase endpoints are also available via the agent's assigned knowledgebase. Use these endpoints when you want to work with an agent's knowledge without knowing the knowledgebase ID directly. The responses are identical to the knowledgebase ID endpoints.
/api/v1/agents/:agentId/knowledgebaseGet the knowledgebase assigned to an agent with all its items (webpages, documents, and references)
Path Parameters
agentIdstringrequiredThe unique identifier (UUID) of the agent
Responses
{
"data": {
"agent": {
"id": "agent-uuid-1234",
"name": "Customer Support Agent"
},
"knowledgebase": {
"id": "kb-uuid-1234",
"name": "Customer Support KB",
"description": "Knowledge base for support agents",
"webpages": [
{
"id": "webpage-uuid-1",
"url": "https://example.com/faq",
"name": "FAQ Page",
"lastScrapedAt": "2024-01-15T10:00:00.000Z",
"isUpdating": false
}
],
"documents": [
{
"id": "doc-uuid-1",
"fileName": "product-manual.pdf",
"name": "Product Manual",
"isUpdating": false
}
],
"references": [
{
"id": "ref-uuid-1",
"question": "What are your business hours?",
"answer": "We are open Monday to Friday, 9 AM to 5 PM EST.",
"type": "QA"
}
]
}
}
}{
"error": "Agent does not have a knowledgebase assigned"
}API Tester
/api/v1/agents/:agentId/knowledgebase/searchSearch the agent's knowledgebase using our Dhyan Knowledge engine. Each search query costs 1 credit.
Path Parameters
agentIdstringrequiredThe unique identifier (UUID) of the agent
Query Parameters
querystringrequiredThe search query - what you want to find (max 2000 characters)
limitintegerMaximum number of results to return (default: 10, max: 50)
thresholdnumberMinimum similarity threshold from 0 to 1 (default: 0.1)
Responses
{
"data": [
{
"id": "ref-uuid-1",
"question": "What are your business hours?",
"answer": "We are open Monday to Friday, 9 AM to 5 PM EST.",
"similarity": 0.892,
"type": "QA",
"source": "manual"
}
],
"meta": {
"agentId": "agent-uuid-1234",
"agentName": "Customer Support Agent",
"knowledgebaseId": "kb-uuid-1234",
"query": "What time are you open?",
"resultCount": 1,
"limit": 10,
"threshold": 0.1,
"creditsUsed": 1
}
}API Tester
Other Agent-Based Endpoints
All knowledgebase item endpoints are available via the agent path. These work identically to their knowledgebase ID counterparts:
GET/PUT/api/v1/agents/:agentId/knowledgebase/webpages/:webpageIdPOST/api/v1/agents/:agentId/knowledgebase/webpages/:webpageId/refreshGET/PUT/api/v1/agents/:agentId/knowledgebase/documents/:documentIdGET/PUT/api/v1/agents/:agentId/knowledgebase/references/:referenceId