# Agent Knowledge Bases

Manage Retell-backed knowledge bases for voice agents. Each KB stores documents that agents can retrieve during calls. KBs can be seeded from help center articles or populated with custom content. Required scopes: voice-kbs:read, voice-kbs:write, voice-kbs:delete. NOTE: Retell KB write API (create and add-sources) is occasionally unavailable -- if create or add_doc returns a 500, this is a Retell-side outage, not a TrustPager bug.

**Base URL:** `https://api.trustpager.com/functions/v1/api/v1`

## Endpoints

### GET /voice-agent-kbs

List all knowledge bases for the workspace.

**Scopes:** `voice-kbs:read` — [full detail](./voice-agent-kbs/get-voice-agent-kbs.md)

### GET /voice-agent-kbs/:id

Get a single knowledge base by ID, including all document records.

**Scopes:** `voice-kbs:read` — [full detail](./voice-agent-kbs/get-voice-agent-kbs-id.md)

### POST /voice-agent-kbs

Create a new knowledge base. source="help_center" seeds it with all help center articles automatically. source="custom" (default) starts empty or accepts initial_texts. WARNING: Retell KB create API returns 500 intermittently -- this is a Retell-side outage.

**Scopes:** `voice-kbs:write` — [full detail](./voice-agent-kbs/post-voice-agent-kbs.md)

### DELETE /voice-agent-kbs/:id

Delete a knowledge base. Removes it from Retell (best-effort, tolerates 404) and deletes all local document rows. Does NOT detach from voice agents -- detach first if needed.

**Scopes:** `voice-kbs:delete` — [full detail](./voice-agent-kbs/delete-voice-agent-kbs-id.md)

### GET /voice-agent-kbs/:kb_id/documents

List all document records tracked for a knowledge base. Each row has a retell_doc_id, source_type (help_center_article or manual), optional source_id (article UUID), title, and content_hash.

**Scopes:** `voice-kbs:read` — [full detail](./voice-agent-kbs/get-voice-agent-kbs-kb-id-documents.md)

### POST /voice-agent-kbs/:kb_id/documents

Add a manually written document to a knowledge base. Pushes the text to Retell and stores a local tracking row. WARNING: Retell add-sources API returns 500 intermittently.

**Scopes:** `voice-kbs:write` — [full detail](./voice-agent-kbs/post-voice-agent-kbs-kb-id-documents.md)

### DELETE /voice-agent-kbs/:kb_id/documents/:doc_id

Remove a document from a knowledge base. Deletes the Retell source (best-effort) and the local tracking row. doc_id is the local UUID from the documents list, not the Retell source ID.

**Scopes:** `voice-kbs:delete` — [full detail](./voice-agent-kbs/delete-voice-agent-kbs-kb-id-documents-doc-id.md)

### POST /voice-agent-kbs/:kb_id/sync-help-center

Sync all help center articles into a knowledge base. Adds new articles, updates changed articles (by content hash), removes deleted articles, skips unchanged ones. Returns added/updated/unchanged/removed/failed counts.

**Scopes:** `voice-kbs:write` — [full detail](./voice-agent-kbs/post-voice-agent-kbs-kb-id-sync-help-center.md)

### POST /voice-agent-kbs/:kb_id/attach/:agent_id

Attach a knowledge base to a voice agent conversation flow. Reads the current flow from Retell, adds the KB ID to knowledge_base_ids (deduped), and saves the updated draft. The agent must be published separately for the change to go live. Returns already_attached:true if already linked.

**Scopes:** `voice-kbs:write` — [full detail](./voice-agent-kbs/post-voice-agent-kbs-kb-id-attach-agent-id.md)