Sources#

These endpoints add knowledge to an agent and remove it again. Sources are what the agent answers from: files, texts, websites and Q&A pairs. Sources overview explains them for people who use the dashboard.

For example, when your team publishes a new policy in your own system, a script can add it to the support agent as a text. The agent can answer from it a few seconds later.

Read the overview first for the base URL, keys, errors and paging.

The source object#

Files, texts and websites share one shape. A field that doesn't apply to a kind is null.

{
  "id": "0199f3c1-2b3a-7d4e-9f50-6a7b8c9d0e1f",
  "kind": "file",
  "name": "returns-policy.pdf",
  "mime_type": "application/pdf",
  "size_kb": 412,
  "length_pages": null,
  "status": "uploaded",
  "created_at": "2026-10-25T09:20:11+00:00"
}

Training turns a source into small, searchable pieces called chunks. The status tells you how far it got:

To know when a source is ready, call List sources every few seconds and watch its status. There is no notification.

List sources#

Returns the agent's files, texts and websites, newest first. Q&A pairs are not in this list.

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

Who can call it: anyone with access to the agent.

curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/sources \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": [source, …], "next_cursor": … }. See Pagination.

Add a file#

Uploads a document, spreadsheet, presentation, image, recording or video as a source.

POST /api/v1/agents/{agent}/sources/files

Who can call it: the owner, or a teammate with Train Files. This one permission covers audio and video files too.

Send the file as multipart/form-data in a field called file:

curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/sources/files \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -F "[email protected]"

The answer is 201 Created with { "data": source }. The status is uploaded.

The upload is refused with a 422 when:

• the file type is not turned on. The admin of your Chatvia server chooses the types in Knowledge settings. File sources lists every type Chatvia can read.
• the type is turned on but the server can't read this file. For example, the program it needs is missing, or a recording is in a format the speech to text service doesn't take. See AI models.
• the file is a PDF locked with a password.

Unlike the dashboard, the API does not refuse a file your workspace has uploaded before. Uploading the same file twice gives you two sources.

Add a text#

Adds a block of plain text as a source. Training starts on its own.

POST /api/v1/agents/{agent}/sources/texts

Who can call it: the owner, or a teammate with Train Text.

curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/sources/texts \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Our return policy. You can return any item within 30 days of delivery. ..." }'

{
  "data": {
    "id": "0199f3c4-8e1f-7a2b-b3c4-d5e6f7a8b9c0",
    "kind": "text",
    "name": "Our return policy. You can return any item within 30 day...",
    "mime_type": null,
    "size_kb": null,
    "length_pages": 1,
    "status": "pending",
    "created_at": "2026-10-25T09:22:40+00:00"
  }
}

The status moves from pending to ingesting to ingested, usually within seconds.

Add a website#

Adds a website as a source and starts finding its pages.

POST /api/v1/agents/{agent}/sources/urls

Who can call it: the owner, or a teammate with Train Web.

curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/sources/urls \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://help.example.com", "include_paths": "/articles/*" }'

{
  "data": {
    "id": "0199f3c6-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "kind": "url",
    "name": "https://help.example.com",
    "mime_type": null,
    "size_kb": null,
    "length_pages": null,
    "status": "crawling",
    "created_at": "2026-10-25T09:25:02+00:00"
  }
}

Chatvia opens the address once to follow a redirect. When the address redirects, the source keeps the address it lands on. Then the pages are found in the background, up to 1,000 of them, and the status becomes crawled.

The request is refused with a 422 when:

• the agent already has this website.
• the address is not public, for example a private network address.
• Chatvia can't open the address.

Finding the pages needs Firecrawl, set by the admin of your Chatvia server in Knowledge settings. Without it the crawl fails.

Add a Q&A pair#

Adds a question and the exact answer the agent should give. When a chatter asks one of the questions, or something very close, the agent replies with your answer word for word. Q&A pairs explains how the match works. Q&A pairs need no training, so they have no status.

POST /api/v1/agents/{agent}/sources/qas

Who can call it: the owner, or a teammate with Train Q&A.

curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/sources/qas \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Cancel a subscription",
    "questions": ["How do I cancel my subscription?", "Where do I unsubscribe?"],
    "answer": "You can cancel from Settings, then Billing. Your access continues until the end of the billing period."
  }'

{
  "data": {
    "id": "0199f3c8-5d6e-7f80-9a1b-2c3d4e5f6a7b",
    "title": "Cancel a subscription",
    "questions": ["How do I cancel my subscription?", "Where do I unsubscribe?"],
    "answer": "You can cancel from Settings, then Billing. Your access continues until the end of the billing period.",
    "created_at": "2026-10-25T09:27:31+00:00"
  }
}

Keep the id from this answer. The API has no endpoint that lists Q&A pairs, so it is the only way to delete the pair later through the API.

Delete a source#

Each kind has its own delete endpoint. Use the id of the source.

DELETE /api/v1/agents/{agent}/sources/files/{id}
DELETE /api/v1/agents/{agent}/sources/texts/{id}
DELETE /api/v1/agents/{agent}/sources/urls/{id}
DELETE /api/v1/agents/{agent}/sources/qas/{id}

Who can call it: the owner, or a teammate with Delete sources.

curl -X DELETE https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/sources/files/0199f3c1-2b3a-7d4e-9f50-6a7b8c9d0e1f \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is 204 No Content. A source that the agent in the path doesn't use is a 404.

Good to know:

• Deleting removes the source and its chunks. A source that is still training stops first.
• A file, text or website is deleted for good, also from other agents that use it. The dashboard can remove a file from one agent only. The API can't.
• Past conversations keep their text. New questions can't find the deleted source.