---
title: "Knowledge Sources"
description: "Add, check, and delete an agent's knowledge through the Chatvox API: text, Q&A, web pages, sitemaps, and files."
---

Use the knowledge API to keep an agent's knowledge in sync with your own systems, for example to push help articles or product data whenever they change. Sources work exactly like the ones you add in the [Knowledge](/docs/knowledge) tab, and count towards your team's [knowledge storage](/docs/billing/usage-and-limits).

## The source object

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The source's ID. |
| `agent_id` | string | The agent it belongs to. |
| `parent_id` | string or null | For pages found from a sitemap, the sitemap's ID. |
| `type` | string | `text`, `qa`, `url`, `sitemap`, or `file`. |
| `name` | string | The title, question, URL, or file name. |
| `url` | string or null | The web address, for `url` and `sitemap` sources. |
| `status` | string | Processing status. See [Source statuses](#source-statuses). |
| `error` | string or null | Why processing failed, when `status` is `failed`. |
| `created_at` | string | When it was added. |
| `updated_at` | string | When it last changed. |

### Source statuses

New sources are processed in the background. The agent can only use a source once it's `indexed`.

| `status` | Meaning |
| --- | --- |
| `pending` | Waiting to be processed. |
| `scanning` | The file is being checked (files only). |
| `processing` | Text is being extracted and split. |
| `embedding` | The source is being made searchable. |
| `indexed` | **Ready.** The agent uses it in answers. |
| `failed` | Processing failed. See `error`. |

## List sources

```http
GET /api/v1/agents/{agent}/sources
```

Returns a [paginated list](/docs/developers#lists-and-pagination) of top-level sources, newest first. Add `?type=file` (or `text`, `qa`, `url`, `sitemap`) to filter by type. Pages found from a sitemap aren't listed; [get them by ID](#get-a-source).

## Add a source

```http
POST /api/v1/agents/{agent}/sources
```

Send a `type` and that type's fields:

| `type` | Fields | Notes |
| --- | --- | --- |
| `text` | `name` (up to 255 characters), `content` | Plain text, such as an article or policy. |
| `qa` | `question` (up to 255 characters), `answer` | One question and its answer. |
| `url` | `url` | One public web page. |
| `sitemap` | `url` | A sitemap's address. Every page in it is added as a child source. |
| `file` | `file` | `.pdf`, `.doc`, `.docx`, `.txt`, `.md`, or `.csv`, up to 20 MB. Send as `multipart/form-data`. |

**Text**

```bash
curl -X POST https://my.chatvox.co/api/v1/agents/AGENT_ID/sources \
  -H "Authorization: Bearer cvx_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "name": "Refund policy",
    "content": "Full refund within 21 days of purchase. After that, we offer store credit."
  }'
```

**Q&A**

```bash
curl -X POST https://my.chatvox.co/api/v1/agents/AGENT_ID/sources \
  -H "Authorization: Bearer cvx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"type": "qa", "question": "Do you ship abroad?", "answer": "Yes, to over 40 countries."}'
```

**Web page**

```bash
curl -X POST https://my.chatvox.co/api/v1/agents/AGENT_ID/sources \
  -H "Authorization: Bearer cvx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"type": "url", "url": "https://example.com/pricing"}'
```

**Sitemap**

```bash
curl -X POST https://my.chatvox.co/api/v1/agents/AGENT_ID/sources \
  -H "Authorization: Bearer cvx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"type": "sitemap", "url": "https://example.com/sitemap.xml"}'
```

**File**

```bash
curl -X POST https://my.chatvox.co/api/v1/agents/AGENT_ID/sources \
  -H "Authorization: Bearer cvx_your_key" \
  -H "Accept: application/json" \
  -F type=file \
  -F file=@handbook.pdf
```

The response is `201 Created` with the new source:

```json
{
  "id": "01a12200-dd5e-7085-878e-a73287c11db3",
  "agent_id": "019f80ad-e549-712d-bc26-3ab29ae2228c",
  "parent_id": null,
  "type": "text",
  "name": "Refund policy",
  "url": null,
  "status": "pending",
  "error": null,
  "created_at": "2026-10-09T18:50:44+00:00",
  "updated_at": "2026-10-09T18:50:44+00:00"
}
```

If the source would take your team over its [knowledge storage](/docs/billing/usage-and-limits), the request fails with `422` and nothing is added.

## Get a source

```http
GET /api/v1/agents/{agent}/sources/{source}
```

Use this to check whether a new source is ready. Poll every few seconds until `status` is `indexed` or `failed`. A short text takes a few seconds; a large PDF or sitemap can take several minutes.

```bash
while true; do
  STATUS=$(curl -s https://my.chatvox.co/api/v1/agents/AGENT_ID/sources/SOURCE_ID \
    -H "Authorization: Bearer cvx_your_key" | jq -r .status)
  echo "$STATUS"
  [ "$STATUS" = "indexed" ] || [ "$STATUS" = "failed" ] && break
  sleep 5
done
```

## Delete a source

```http
DELETE /api/v1/agents/{agent}/sources/{source}
```

Returns `204 No Content`. The source is removed from the agent's knowledge immediately. Deleting a sitemap also removes its pages.

## Updating content

To update a source, add the new version and then delete the old one. Add first so the agent always has the information while the new source is processed.

:::tip
To retrain web pages on a schedule instead, turn on [automatic retraining](/docs/knowledge/retraining) for the agent.
:::

Adding sources is limited to 20 per minute per API key. See [Rate Limits](/docs/developers/errors-and-rate-limits#rate-limits).