> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voice.wixzel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Give your AI phone agent a knowledge base

> Teach a voice agent about your business: write a knowledge base by hand, draft one from your website or a document, add PDFs and Word files the agent searches during calls, then give it to an agent. An agent generated from a website gets one made for it.

A knowledge base is what an agent knows about your business. It has three parts:

| Field | What goes in it |
| - | - |
| `basic_info` | What you do, who for, where you are, opening hours, how to reach you |
| `faqs` | Questions callers ask, each with the answer to give |
| `other_info` | Prices, policies, how booking works, anything else |

It can also hold [files](#files): price lists, menus, manuals and policies that
are too long for those fields. The agent searches them during a call.

An agent uses one knowledge base, set with `knowledge_base_id`. Several agents
can share the same one. The agent's [mascot](/mascots.md) answers from it too, on
the share link and the website widget.

The console does all of this under **Knowledge**, at
[voice.wixzel.com/knowledge](https://voice.wixzel.com/knowledge).

## Write one by hand

```bash theme={null}
curl https://api.voice.wixzel.com/v1/knowledge-bases \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Smile Dental",
    "basic_info": "A family dental clinic in Kochi. Open Monday to Saturday, 9 am to 6 pm.",
    "faqs": [{ "question": "Do you take walk-ins?", "answer": "Yes, until 5 pm." }],
    "other_info": "A cleaning costs ₹800."
  }'
```

## Draft one from a website

`POST /v1/knowledge-bases/import` reads a website, its home page and up to three
pages it links to, and answers with a draft. **Nothing is saved.** Check the
draft, fix anything that is wrong, then create it with the same fields:

```bash theme={null}
curl https://api.voice.wixzel.com/v1/knowledge-bases/import \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com" }'
```

```json theme={null}
{
  "object": "knowledge_base_draft",
  "name": "Smile Dental",
  "description": "Imported from example.com.",
  "basic_info": "A family dental clinic in Kochi…",
  "faqs": [{ "question": "Do you take walk-ins?", "answer": "Yes, until 5 pm." }],
  "other_info": "A cleaning costs ₹800.",
  "source_url": "https://example.com"
}
```

Pass `source_url` along when you create it, so the console can show where it
came from and read the site again later.

Importing takes 10 to 60 seconds and is not charged. Each account can import 5
websites, then one a minute. A website that cannot be reached answers `422
website_unreadable`; one with nothing to learn from answers `422
nothing_to_learn`.

## Draft one from a document

`POST /v1/knowledge-bases/import-file` does the same for one document: PDF,
DOCX, TXT, MD, CSV or HTML, up to 10 MB. Upload it as multipart `file`, or send
JSON `{ "url": "..." }` to fetch it. **Nothing is saved**, and the answer is a
draft like the one above, with `source_url` null.

```bash theme={null}
curl https://api.voice.wixzel.com/v1/knowledge-bases/import-file \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -F "file=@about-us.pdf"
```

A draft keeps the short facts. To let the agent use all of a long document,
add it as a file instead.

## Files

Add documents to a knowledge base, and every agent using it can search them
during calls. The agent does not read them in full on every reply: when a
caller asks something the three fields do not cover, it calls its built-in
`search_knowledge` tool, gets the few passages that match best, and answers
from those.

```bash theme={null}
curl https://api.voice.wixzel.com/v1/knowledge-bases/KB_ID/files \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -F "files=@menu.pdf" \
  -F "files=@price-list.docx"
```

Or fetch one from a public link:

```bash theme={null}
curl https://api.voice.wixzel.com/v1/knowledge-bases/KB_ID/files \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/menu.pdf" }'
```

Each file comes back `processing`. Reading it takes a few seconds, then it is
`ready`, with its `pages` and the number of passages (`chunks`) the agent can
search. A file that cannot be read is `failed`, with the reason in `error`.

```json theme={null}
{
  "object": "knowledge_file",
  "id": "6720...",
  "knowledge_base_id": "671f...",
  "name": "menu.pdf",
  "kind": "pdf",
  "bytes": 182044,
  "pages": 4,
  "chars": 9120,
  "chunks": 12,
  "status": "ready",
  "error": null,
  "source_url": null,
  "created_at": "2026-10-20T09:30:00.000Z"
}
```

| Route | Does |
| - | - |
| `GET /v1/knowledge-bases/{id}/files` | The files, newest first |
| `POST /v1/knowledge-bases/{id}/files` | Add up to 5 as multipart `files`, or one as JSON `{ url, name? }` |
| `GET /v1/knowledge-bases/{id}/files/{fileId}` | One file's status |
| `DELETE /v1/knowledge-bases/{id}/files/{fileId}` | Remove it and what the agent could find in it |

* PDF, DOCX, TXT, MD, CSV and HTML, up to 10 MB each, 20 files per knowledge base.
* Scanned PDFs, with no text in them, are read as images.
* Only the text is kept, cut into passages. The file itself is not stored, so
  there is nothing to download again.
* Deleting the knowledge base deletes its files.

Searches show on the call record as `tool_calls` of type `knowledge`, with the
question the agent asked.

## Give it to an agent

```bash theme={null}
curl -X PATCH https://api.voice.wixzel.com/v1/agents/AGENT_ID \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "knowledge_base_id": "KB_ID" }'
```

Send `"knowledge_base_id": null` to take it away again. Deleting a knowledge
base removes it from every agent that used it.

## Agents made from a website

`POST /v1/agents/generate` with a `website_url` makes an agent and reads the
site in the background. The agent gets a knowledge base drafted from the site,
saved straight away. Edit it afterwards like any other.

```bash theme={null}
curl https://api.voice.wixzel.com/v1/agents/generate \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "website_url": "https://example.com", "role": "receptionist" }'
```

A new look for an agent's mascot, with
`POST /v1/agents/{id}/mascot/generate` and a `website_url`, keeps the agent's
knowledge base as it is: the website only sets the look. Send
`"refresh_knowledge": true` to rewrite the knowledge base from the website
instead. That also changes what the agent says on phone calls. If the agent has
no knowledge base, one is made from the website and given to it. See
[Mascots](/mascots.md).

## Keep it short

The three fields are read on every reply, not searched, so their length adds
time to each answer. Keep them to what callers ask about most. Up to about
8,000 characters stays quick; past 20,000 replies get noticeably slower. Put
anything longer in [files](#files), which cost nothing until the agent
searches them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.