Knowledge Sources

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 tab, and count towards your team’s knowledge storage.

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.
`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

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

Returns a paginated list 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.

Add a source

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`.

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."
  }'

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."}'

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"}'

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"}'

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:

{
  "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, the request fails with 422 and nothing is added.

Get a source

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.

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

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.

Adding sources is limited to 20 per minute per API key. See Rate Limits.