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": "Example name",
6  "description": "Example description."
7}'
Try it
2

Add content

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

StatusMeaning
fetchingUrl-sourced document is being scraped. File and text documents skip this state.
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

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": "example",
6  "kb_ids": [
7    "kb_01jqr8x9zg5k2m3n4p5q6r7s8t"
8  ],
9  "limit": 50
10}'
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