Documents your agents answer from. A base holds markdown or plain-text documents, read in the background; an agent links up to 3 bases with knowledge_base_ids. Small knowledge sits whole in the agent's prompt and larger knowledge is searched during the call, by keyword and, optionally, by meaning on your own Google or OpenAI account. Dvaarik charges nothing for it.
Every example below runs as written once these are exported:
bash
export DVAARIK_API_KEY="dvk_..."# project API key, server side only
export DVAARIK_TOKEN="<account access token>"# console session, from POST /console/auth/login
export BASE_ID="<uuid>"
export DOCUMENT_ID="<uuid>"
export PROJECT_ID="<uuid>"
A <value> inside a JSON body is a value you supply. Responses are JSON; every error body is { "detail": … }. Each schema is expanded once per page, where it first appears.
A 422 from a route that also refuses with a sentence: FastAPI's list of field errors when the body or query does not parse, or one sentence when it parsed and was refused.
Field
Type
Required
Notes
detail
string or ValidationErrorItem[]
yes
A sentence for the developer, or the list of fields that failed validation.
Error
When
401
No API key was sent in X-Api-Key, or it is invalid or revoked.
403
The API key lacks the scope this route needs, or its account or project is unavailable.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
429
The project's requests-per-minute limit is reached; Retry-After says when to try again.
Plus the machine-door errors above. Full list on the errors page.
bash
curl -sS -X GET "https://api.developers.dvaarik.com/v2/knowledge-bases" \
-H "X-Api-Key: $DVAARIK_API_KEY"
Make a knowledge base, at most 10 per project. Leave out embedding_account_id for keyword search, which needs no setup; name a verified Google or OpenAI account of this project for keyword + meaning search on it.
Rename it or change its search. Only the fields you send change. The same embedding_account_id again retries what is not fully indexed; another account, or null, reads every document again.
Fields left out stay as they are; embedding_account_id: null turns meaning-based search off. Saving the SAME embedding_account_id again re-indexes every document that is not fully embedded (the retry after a provider failure); an account with the same provider re-embeds nothing that already has vectors; any other change re-indexes every document.
Field
Type
Required
Notes
description
string or null
no
embedding_account_id
uuid or null
no
name
string or null
no
Error
When
401
No API key was sent in X-Api-Key, or it is invalid or revoked.
403
The API key lacks the scope this route needs, or its account or project is unavailable.
404
The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed.
409
A limit or the resource's state refuses this change; the sentence says which.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
429
The project's requests-per-minute limit is reached; Retry-After says when to try again.
Plus the machine-door errors above. Full list on the errors page.
Add a document, at most 50 per base. It is saved queued and read in the background; agents use it once it is ready.
Detail
Value
Door
Project API key — X-Api-Key: $DVAARIK_API_KEY
Scope
voice:write
Operation
createKnowledgeDocument
Success
201KnowledgeDocumentInfo
Parameter
In
Type
Required
Notes
base_id
path
uuid
yes
name
query
string
yes
The document's name, 1 to 200 characters. A raw upload (text/markdown, text/plain or application/pdf body) is named only by this and is refused without it. A JSON body carries its own name, which is the one used; this parameter is not read for JSON.
No API key was sent in X-Api-Key, or it is invalid or revoked.
403
The API key lacks the scope this route needs, or its account or project is unavailable.
404
The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
429
The project's requests-per-minute limit is reached; Retry-After says when to try again.
Plus the machine-door errors above. Full list on the errors page.
bash
curl -sS -X GET "https://api.developers.dvaarik.com/v2/knowledge-bases/$BASE_ID/documents/$DOCUMENT_ID" \
-H "X-Api-Key: $DVAARIK_API_KEY"
PUT /v2/knowledge-bases/{base_id}/documents/{document_id}#
Replace a document's text. The previous version keeps answering until the new one is ready.
Detail
Value
Door
Project API key — X-Api-Key: $DVAARIK_API_KEY
Scope
voice:write
Operation
replaceKnowledgeDocument
Success
200KnowledgeDocumentInfo
Parameter
In
Type
Required
Notes
base_id
path
uuid
yes
document_id
path
uuid
yes
name
query
string
yes
The document's name, 1 to 200 characters. A raw upload (text/markdown, text/plain or application/pdf body) is named only by this and is refused without it. A JSON body carries its own name, which is the one used; this parameter is not read for JSON.
Request body: KnowledgeDocumentCreate.
Error
When
401
No API key was sent in X-Api-Key, or it is invalid or revoked.
403
The API key lacks the scope this route needs, or its account or project is unavailable.
404
The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed.
409
A limit or the resource's state refuses this change; the sentence says which.
413
The request body is larger than this route accepts; the sentence names the limit.
415
This route does not read that Content-Type; the sentence names the ones it does.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
429
The project's requests-per-minute limit is reached; Retry-After says when to try again.
503
A bounded worker this request needs is busy; Retry-After says when to try again.
Plus the machine-door errors above. Full list on the errors page.
No API key was sent in X-Api-Key, or it is invalid or revoked.
403
The API key lacks the scope this route needs, or its account or project is unavailable.
404
The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
429
The project's requests-per-minute limit is reached; Retry-After says when to try again.
Plus the machine-door errors above. Full list on the errors page.
bash
curl -sS -X POST "https://api.developers.dvaarik.com/v2/knowledge-bases/$BASE_ID/search" \
-H "X-Api-Key: $DVAARIK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "What time do you open on Saturday?"
}'
No account session was presented, or it is invalid or expired.
403
The account is suspended or its email is not verified.
404
The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
Plus the account-door errors above. Full list on the errors page.
bash
curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases" \
-H "Authorization: Bearer $DVAARIK_TOKEN"
POST /console/v2/projects/{project_id}/knowledge-bases#
Make a knowledge base, at most 10 per project. Leave out embedding_account_id for keyword search, which needs no setup; name a verified Google or OpenAI account of this project for keyword + meaning search on it.
No account session was presented, or it is invalid or expired.
403
The account is suspended or its email is not verified.
404
The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
409
The project or resource is in a state that refuses this change.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
Plus the account-door errors above. Full list on the errors page.
No account session was presented, or it is invalid or expired.
403
The account is suspended or its email is not verified.
404
The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
409
The project or resource is in a state that refuses this change.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
Plus the account-door errors above. Full list on the errors page.
No account session was presented, or it is invalid or expired.
403
The account is suspended or its email is not verified.
404
The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
Plus the account-door errors above. Full list on the errors page.
bash
curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID" \
-H "Authorization: Bearer $DVAARIK_TOKEN"
Rename it or change its search. Only the fields you send change. The same embedding_account_id again retries what is not fully indexed; another account, or null, reads every document again.
No account session was presented, or it is invalid or expired.
403
The account is suspended or its email is not verified.
404
The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
409
The project or resource is in a state that refuses this change.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
Plus the account-door errors above. Full list on the errors page.
No account session was presented, or it is invalid or expired.
403
The account is suspended or its email is not verified.
404
The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
Plus the account-door errors above. Full list on the errors page.
bash
curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID/documents" \
-H "Authorization: Bearer $DVAARIK_TOKEN"
POST /console/v2/projects/{project_id}/knowledge-bases/{base_id}/documents#
Add a document, at most 50 per base. It is saved queued and read in the background; agents use it once it is ready.
The document's name, 1 to 200 characters. A raw upload (text/markdown, text/plain or application/pdf body) is named only by this and is refused without it. A JSON body carries its own name, which is the one used; this parameter is not read for JSON.
Request body: KnowledgeDocumentCreate.
Error
When
401
No account session was presented, or it is invalid or expired.
403
The account is suspended or its email is not verified.
404
The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
409
The project or resource is in a state that refuses this change.
413
The request body is larger than this route accepts; the sentence names the limit.
415
This route does not read that Content-Type; the sentence names the ones it does.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
503
A bounded worker this request needs is busy; Retry-After says when to try again.
Plus the account-door errors above. Full list on the errors page.
No account session was presented, or it is invalid or expired.
403
The account is suspended or its email is not verified.
404
The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
409
The project or resource is in a state that refuses this change.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
Plus the account-door errors above. Full list on the errors page.
No account session was presented, or it is invalid or expired.
403
The account is suspended or its email is not verified.
404
The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
Plus the account-door errors above. Full list on the errors page.
bash
curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID/documents/$DOCUMENT_ID" \
-H "Authorization: Bearer $DVAARIK_TOKEN"
PUT /console/v2/projects/{project_id}/knowledge-bases/{base_id}/documents/{document_id}#
Replace a document's text. The previous version keeps answering until the new one is ready.
The document's name, 1 to 200 characters. A raw upload (text/markdown, text/plain or application/pdf body) is named only by this and is refused without it. A JSON body carries its own name, which is the one used; this parameter is not read for JSON.
Request body: KnowledgeDocumentCreate.
Error
When
401
No account session was presented, or it is invalid or expired.
403
The account is suspended or its email is not verified.
404
The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
409
The project or resource is in a state that refuses this change.
413
The request body is larger than this route accepts; the sentence names the limit.
415
This route does not read that Content-Type; the sentence names the ones it does.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
503
A bounded worker this request needs is busy; Retry-After says when to try again.
Plus the account-door errors above. Full list on the errors page.
No account session was presented, or it is invalid or expired.
403
The account is suspended or its email is not verified.
404
The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
409
The project or resource is in a state that refuses this change.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
Plus the account-door errors above. Full list on the errors page.
bash
curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID/reindex" \
-H "Authorization: Bearer $DVAARIK_TOKEN"
POST /console/v2/projects/{project_id}/knowledge-bases/{base_id}/search#
Try a question: exactly the passages an agent's search_knowledge tool gets on a call, with the mode used and the time taken.
No account session was presented, or it is invalid or expired.
403
The account is suspended or its email is not verified.
404
The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
422
The request body or query is not valid. detail is an array of {loc, msg, type} and loc names the offending field.
Plus the account-door errors above. Full list on the errors page.
bash
curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID/search" \
-H "Authorization: Bearer $DVAARIK_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"query": "What time do you open on Saturday?"
}'
Try it without a key in the browser
The playground opens a real voice session with your account session, so a project key never reaches a browser. Machine calls belong on your own server.