Knowledge Bases

Manage knowledge bases that agents can reference during calls. Creating a knowledge base is a two-step process:

Create the knowledge base (name + description only).
Add sources — upload files, paste text, or crawl URLs. Each source is indexed independently and has its own status.

For UUID / phone / datetime formats used below, see Data formats.

List Knowledge Bases

Parameters

Query parameters:

Parameter	Type	Default	Description
`name`	string	—	Filter by name (case-insensitive substring match)
`limit`	integer	`50`	1–100
`offset`	integer	`0`	Pagination offset

Returns data (array of knowledge base objects), pagination, and meta.

cURL

curl "https://api.truedy.ai/api/public/v1/knowledge-bases" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Knowledge Base

Returns data (knowledge base object) and meta.

curl "https://api.truedy.ai/api/public/v1/knowledge-bases/6f4af8be-0a96-49b0-ac2a-a359f46cc966" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Knowledge Base

Create an empty knowledge base. Add content via Add Document Source or Add Web Source after creation.

Parameters

Request body:

Field	Type	Required	Description
`name`	string	Yes	Display name for the knowledge base
`description`	string	No	Optional description

cURL

curl -X POST "https://api.truedy.ai/api/public/v1/knowledge-bases" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FAQ",
    "description": "Frequently asked questions"
  }'

Response: 201 Created with data (knowledge base object, status: "ready") and meta.

Update Knowledge Base

Update the name or description. Only included fields are changed. To update content, add or delete sources.

Parameters

Request body:

Field	Type	Description
`name`	string	New display name
`description`	string	New description

cURL

curl -X PATCH "https://api.truedy.ai/api/public/v1/knowledge-bases/6f4af8be-0a96-49b0-ac2a-a359f46cc966" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FAQ - Updated",
    "description": "Revised Q&A content"
  }'

Delete Knowledge Base

Permanently deletes the knowledge base, all its sources, and removes it from Ultravox. Agents that reference this knowledge base will no longer have access to it.

curl -X DELETE "https://api.truedy.ai/api/public/v1/knowledge-bases/6f4af8be-0a96-49b0-ac2a-a359f46cc966" \
  -H "Authorization: Bearer YOUR_API_KEY"

List Sources

List all sources attached to a knowledge base. Source statuses are synced in real-time. Poll this endpoint every 5–10 seconds while any source has status: "scanning" to track indexing progress.

curl "https://api.truedy.ai/api/public/v1/knowledge-bases/6f4af8be-0a96-49b0-ac2a-a359f46cc966/sources" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "3a1bc2d4-0000-4000-8000-000000000001",
      "kb_id": "6f4af8be-0a96-49b0-ac2a-a359f46cc966",
      "name": "Company FAQ",
      "description": null,
      "kind": "document",
      "status": "ready",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:01:00Z"
    }
  ],
  "meta": { "request_id": "...", "ts": "2024-01-01T00:00:00Z" }
}

Add Document Source

Upload a file (PDF, TXT, DOCX, or Markdown) as a source. The file is base64-encoded in the request body. Maximum file size: 50 MB.

Parameters

Request body:

Field	Type	Required	Description
`name`	string	Yes	Display name for this source
`description`	string	No	Optional description
`file`	object	Yes	File to upload (see below)

file object:

Field	Type	Description
`filename`	string	File name including extension (e.g. `policy.pdf`)
`data`	string	Base64-encoded file content
`content_type`	string	MIME type: `application/pdf`, `text/plain`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `text/markdown`

cURL

curl -X POST "https://api.truedy.ai/api/public/v1/knowledge-bases/6f4af8be-0a96-49b0-ac2a-a359f46cc966/sources/document" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Return Policy",
    "description": "Our standard 30-day return policy",
    "file": {
      "filename": "return-policy.pdf",
      "data": "JVBERi0xLjQKJcfs...",
      "content_type": "application/pdf"
    }
  }'

Response: 201 Created with data (source object with initial status: "scanning") and meta. Poll List Sources until status becomes ready or failed.

Add Web Source

Crawl one or more URLs and index their content as a source. The crawler follows links up to max_depth levels.

Parameters

Request body:

Field	Type	Required	Description
`name`	string	Yes	Display name for this source
`description`	string	No	Optional description
`urls`	string[]	Yes	One or more URLs to crawl
`max_depth`	integer	No	Link-follow depth. `0` = page only, `1` = one level of links (default). Max `3`.

cURL

curl -X POST "https://api.truedy.ai/api/public/v1/knowledge-bases/6f4af8be-0a96-49b0-ac2a-a359f46cc966/sources/web" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Help Center",
    "description": "Indexed from our help site",
    "urls": [
      "https://help.example.com/faq",
      "https://help.example.com/pricing",
      "https://help.example.com/getting-started"
    ],
    "max_depth": 1
  }'

Response: 201 Created with data (source object with initial status: "scanning") and meta. Poll List Sources until status becomes ready or failed.

Delete Source

Remove a source from a knowledge base. The indexed content for this source is permanently deleted from Ultravox.

curl -X DELETE "https://api.truedy.ai/api/public/v1/knowledge-bases/6f4af8be-0a96-49b0-ac2a-a359f46cc966/sources/3a1bc2d4-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Knowledge Base Object

Field	Type	Description
`id`	UUID	Knowledge base ID
`name`	string	Display name
`description`	string	Optional description
`status`	string	`ready` — available to agents; `creating` — being set up
`language`	string	Content language (e.g. `en-US`)
`created_at`	datetime	When the knowledge base was created
`updated_at`	datetime	Last updated

Source Object

Field	Type	Description
`id`	UUID	Source ID
`kb_id`	UUID	Parent knowledge base ID
`name`	string	Display name
`description`	string	Optional description
`kind`	string	`document` (file upload) or `web` (URL crawl)
`status`	string	`pending` — queued; `scanning` — indexing in progress; `ready` — fully indexed; `failed` — indexing error
`created_at`	datetime	When the source was added
`updated_at`	datetime	Last updated

Full Example — Create KB and Add Sources

# Step 1: Create the knowledge base
KB_ID=$(curl -s -X POST "https://api.truedy.ai/api/public/v1/knowledge-bases" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Customer Support KB"}' | jq -r '.data.id')

# Step 2a: Add a PDF document
curl -X POST "https://api.truedy.ai/api/public/v1/knowledge-bases/$KB_ID/sources/document" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Product Manual\",
    \"file\": {
      \"filename\": \"manual.pdf\",
      \"data\": \"$(base64 -i manual.pdf)\",
      \"content_type\": \"application/pdf\"
    }
  }"

# Step 2b: Add a web crawl source
curl -X POST "https://api.truedy.ai/api/public/v1/knowledge-bases/$KB_ID/sources/web" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Help Center",
    "urls": ["https://help.example.com/faq"],
    "max_depth": 1
  }'

# Step 3: Poll until all sources are ready
curl "https://api.truedy.ai/api/public/v1/knowledge-bases/$KB_ID/sources" \
  -H "Authorization: Bearer YOUR_API_KEY"

​Knowledge Bases

​List Knowledge Bases

​Parameters

​cURL

​Get Knowledge Base

​Create Knowledge Base

​Parameters

​cURL

​Update Knowledge Base

​Parameters

​cURL

​Delete Knowledge Base

​List Sources

​Add Document Source

​Parameters

​cURL

​Add Web Source

​Parameters

​cURL

​Delete Source

​Knowledge Base Object

​Source Object

​Full Example — Create KB and Add Sources

Knowledge Bases

List Knowledge Bases

Parameters

cURL

Get Knowledge Base

Create Knowledge Base

Parameters

cURL

Update Knowledge Base

Parameters

cURL

Delete Knowledge Base

List Sources

Add Document Source

Parameters

cURL

Add Web Source

Parameters

cURL

Delete Source

Knowledge Base Object

Source Object

Full Example — Create KB and Add Sources