Give Dyvas specialized knowledge by uploading documents. Files are chunked, embedded, and used for RAG during conversations.
Send a document via multipart/form-data. Formats: .txt, .pdf, .md, .csv, .json (max 10 MB).
Split into overlapping text chunks optimized for semantic search.
Each chunk is converted to a vector embedding and stored.
User messages are embedded at query time and the most relevant chunks are injected into context.
/v1/knowledge/:dyva_id/documentsAuth RequiredUpload a document. Processed asynchronously — poll the detail endpoint for status.
| Name | Type | Required | Description |
|---|---|---|---|
dyva_id | string | Required | The unique identifier of the Dyva. |
| Name | Type | Required | Description |
|---|---|---|---|
file | file | Required | The document file. Supported formats: .txt, .pdf, .md, .csv, .json. Maximum size: 10 MB. |
{
"id": "doc_8f3a1b2c4d5e",
"dyva_id": "dyva_01j7kx9m3p",
"filename": "product-faq.pdf",
"size_bytes": 245780,
"chunk_count": null,
"status": "processing",
"created_at": "2026-03-09T14:22:08Z"
}curl -X POST https://api.dyva.ai/v1/knowledge/dyva_01j7kx9m3p/documents \
-H "Authorization: Bearer sk_live_..." \
-F "file=@product-faq.pdf"/v1/knowledge/:dyva_id/documentsAuth RequiredList knowledge base documents, newest first. Paginated.
| Name | Type | Required | Description |
|---|---|---|---|
dyva_id | string | Required | The unique identifier of the Dyva. |
{
"data": [
{
"id": "doc_8f3a1b2c4d5e",
"filename": "product-faq.pdf",
"size_bytes": 245780,
"chunk_count": 34,
"status": "ready",
"created_at": "2026-03-09T14:22:08Z"
},
{
"id": "doc_6e9d0c7b8a12",
"filename": "return-policy.md",
"size_bytes": 8192,
"chunk_count": 5,
"status": "ready",
"created_at": "2026-03-08T09:15:33Z"
},
{
"id": "doc_3c4f5a6b7d8e",
"filename": "inventory.csv",
"size_bytes": 1048576,
"chunk_count": null,
"status": "processing",
"created_at": "2026-03-09T14:30:01Z"
}
],
"total": 3,
"limit": 20,
"offset": 0
}/v1/knowledge/:dyva_id/documents/:doc_idAuth RequiredDocument details with processing status and timing.
| Name | Type | Required | Description |
|---|---|---|---|
dyva_id | string | Required | The unique identifier of the Dyva. |
doc_id | string | Required | The unique identifier of the document. |
{
"id": "doc_8f3a1b2c4d5e",
"dyva_id": "dyva_01j7kx9m3p",
"filename": "product-faq.pdf",
"size_bytes": 245780,
"chunk_count": 34,
"status": "ready",
"created_at": "2026-03-09T14:22:08Z",
"processing": {
"started_at": "2026-03-09T14:22:09Z",
"completed_at": "2026-03-09T14:22:18Z",
"duration_ms": 9012
}
}/v1/knowledge/:dyva_id/documents/:doc_idAuth RequiredDelete a document and its embeddings. Cannot be undone.
| Name | Type | Required | Description |
|---|---|---|---|
dyva_id | string | Required | The unique identifier of the Dyva. |
doc_id | string | Required | The unique identifier of the document. |
{
"id": "doc_8f3a1b2c4d5e",
"deleted": true
}/v1/knowledge/:dyva_id/queryAuth RequiredQuery the knowledge base directly. Test what context would be retrieved without starting a conversation.
| Name | Type | Required | Description |
|---|---|---|---|
dyva_id | string | Required | The unique identifier of the Dyva. |
| Name | Type | Required | Description |
|---|---|---|---|
query | string | Required | The natural-language query to search for. |
limit | integer | Optional | Maximum number of chunks to return. Defaults to 5, maximum 20. |
{
"results": [
{
"chunk_id": "chk_a1b2c3d4e5f6",
"document_id": "doc_8f3a1b2c4d5e",
"filename": "product-faq.pdf",
"content": "Our standard return window is 30 days from the date of purchase. Items must be in original packaging and unused condition. Refunds are issued to the original payment method within 5-7 business days.",
"similarity": 0.92,
"chunk_index": 12
},
{
"chunk_id": "chk_f6e5d4c3b2a1",
"document_id": "doc_6e9d0c7b8a12",
"filename": "return-policy.md",
"content": "For defective items, we offer a full refund or replacement regardless of the return window. Contact support with your order number and a photo of the defect.",
"similarity": 0.87,
"chunk_index": 3
}
],
"query": "what is the return policy?",
"total_results": 2
}curl -X POST https://api.dyva.ai/v1/knowledge/dyva_01j7kx9m3p/query \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "query": "what is the return policy?", "limit": 5 }'