How-to guidesKnowledge bases

Create a knowledge base

Create a knowledge base, add content, and attach it to an agent

For how retrieval works, see Knowledge bases.

1

Create the knowledge base

POST
/v1/agents/knowledge-bases
1curl -X POST https://api.speechify.ai/v1/agents/knowledge-bases \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "name": "string"
6}'
Try it
2

Add content

Populate it by uploading documents, importing from a URL, or organizing into folders. Each document reports a status:

StatusMeaning
embeddingChunks are being embedded and inserted.
readyAll chunks indexed; the document is searchable.
failedExtraction or embedding failed — see error.
3

Attach it to an agent

POST
/v1/agents/:id/knowledge-bases/:kbId
1curl -X POST https://api.speechify.ai/v1/agents/id/knowledge-bases/kbId \
2     -H "Authorization: Bearer <token>"
Try it

On the next call, search_knowledge is registered automatically — you don’t change the prompt.

Search via the API

Run semantic search directly — handy for grounded-snippet UIs, or for checking what the agent would retrieve.

POST
/v1/agents/knowledge-bases/search
1curl -X POST https://api.speechify.ai/v1/agents/knowledge-bases/search \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "query": "string",
6  "kb_ids": [
7    "string"
8  ]
9}'
Try it

Each hit includes the source filename, the chunk, and a cosine-similarity score. Scores are relative — use them for ranking, not as an absolute confidence metric.

From the dashboard

On an agent’s Knowledge tab, click + New knowledge base (or attach one you already built). Attached knowledge bases are live on the very next call — no rebuild step.

Knowledge tab with one attached knowledge base
An agent's Knowledge tab with a knowledge base attached