Knowledge base
Knowledge base documents give an agent access to information it can retrieve during a conversation. When a caller asks a question, the agent searches the knowledge base and uses what it finds to construct an accurate answer — rather than relying solely on what its prompt describes.
Typical documents: product catalogues, FAQs, support articles, pricing sheets, terms and conditions.
Document types
| Type | How to create | When to use |
|---|---|---|
url |
POST /knowledge-base/url |
Public web pages the platform fetches and indexes |
text |
POST /knowledge-base/text |
Raw text you supply directly |
file |
POST /knowledge-base/file |
Uploaded files (.txt, .pdf, .docx, .epub, .html) |
Adding documents
From a URL
curl -X POST https://api.simwood.com/convai/v1/knowledge-base/url \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Support FAQ",
"url": "https://example.com/support/faq"
}'
From text
curl -X POST https://api.simwood.com/convai/v1/knowledge-base/text \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Cancellation policy",
"text": "Customers may cancel any subscription within 30 days of purchase..."
}'
From a file
curl -X POST https://api.simwood.com/convai/v1/knowledge-base/file \
-H "Authorization: Bearer sk_live_..." \
-F "name=Product catalogue" \
-F "file=@catalogue.pdf"
The response includes the document's id — save it to reference from agent configurations.
Referencing documents in an agent
Documents are added to an agent's configuration.agent.knowledge_base array. Each entry references a document by its id and the same type it was created with:
"knowledge_base": [
{ "type": "url", "id": "doc-uuid-1", "source": "https://example.com/support/faq" },
{ "type": "text", "id": "doc-uuid-2", "source": "Cancellation policy" },
{ "type": "file", "id": "doc-uuid-3", "source": "catalogue.pdf" }
]
An agent can reference multiple documents. During a conversation it searches across all of them.
Managing documents
# List all documents on your account
curl https://api.simwood.com/convai/v1/knowledge-base \
-H "Authorization: Bearer sk_live_..."
# Retrieve a specific document
curl https://api.simwood.com/convai/v1/knowledge-base/<document-id> \
-H "Authorization: Bearer sk_live_..."
# Delete a document
curl -X DELETE https://api.simwood.com/convai/v1/knowledge-base/<document-id> \
-H "Authorization: Bearer sk_live_..."
Deleting a document does not automatically update agents that reference it. Remove the entry
from configuration.agent.knowledge_base on any affected agent with PUT /agents/:id before
or after deletion.