Sources - Chatbase

The Sources API lets you manage the content your agent is trained on. You can list, inspect, create, update, and delete sources without touching the dashboard. Sources train on write. Creating, updating, or deleting a source takes effect on its own within seconds. There is no separate train call.

Hostname routing

File upload operations use a different base URL from all other endpoints.

Operation	Base URL
All read operations and JSON-body writes	`https://www.chatbase.co/api/v2`
Create or update file sources	`https://files.chatbase.co/api/v2`

Using the wrong host for file uploads will return a 404.

Source types

Type	List	Get	Create	Update	Delete
`text`	✓	✓	✓	✓	✓
`qna`	✓	✓	✓	✓	✓	✓
`link`	✓	✓	✓	✓	✓	✓
`file`	✓	✓	✓	✓	✓	✓
`notionPage`	✓	✓	✗	✗	✓	✓

Notion pages appear in list and get results, but cannot be created or updated via the API. Manage Notion sources through the Notion integration in the dashboard.

Source status

Every source has a status field. It is the completion signal: poll GET /agents/{agentId}/sources/{sourceId} until it reads trained or failed.

Status	Meaning
`untrained`	Just created. Training has started and usually finishes within seconds.
`trained`	Live. The agent answers from this content.
`updated`	Content changed. The new version is training; the old version stays live until it lands.
`toBeDeleted`	Delete in progress. The row disappears once the purge finishes, normally before the DELETE response returns.
`failed`	The last training run did not land. An earlier trained version, if any, stays live. Fix the source (or re-save it) to retry; the dashboard shows the reason.
`deleted`	Removed. Returned only by the DELETE response; never appears in list or get results.

shouldRetrain: true from Get sources summary means at least one source is still untrained, updated, or toBeDeleted. Nothing to do; wait for them to settle.

Editing a source that is training

A source can be edited by one writer at a time. PUT while it is still training returns 409 SOURCE_IS_TRAINING. Wait for trained, then retry. Delete is always accepted.

Deletes are permanent

DELETE removes the source and its knowledge immediately. There is no pending state and no undo. The restore endpoint is deprecated and returns a no-op success.

File upload rate limit

File uploads are limited to 10 per minute per account. Space uploads at least 6 seconds apart. A 429 counts toward the window, so retrying into it keeps it closed; wait, do not retry in a tight loop.

Endpoints

List sources

Paginated list with optional type and name filters

Sources summary

Aggregate counts and sizes per source type

Get source

Retrieve a single source by ID

Create source

Create text, Q&A, and link sources

Create file source

Upload PDF, DOCX, or TXT files

Update source

Update text, Q&A, and link sources

Update file source

Replace file content or rename a file source

Delete source

Permanently remove a source and its knowledge

Restore source (deprecated)

No-op. Deletes are final.

Error codes

Sources-specific error codes beyond the standard authentication and rate-limiting errors:

Code	HTTP	Description
`SOURCE_NOT_FOUND`	404	Source doesn’t exist, belongs to a different agent, or has been permanently deleted.
`SOURCE_TYPE_NOT_SUPPORTED`	400	Attempting to update a `notionPage` via PUT. Manage Notion sources through the dashboard.
`SOURCE_IS_TRAINING`	409	The source is still training. Wait for `trained`, then retry the edit.
`SOURCE_PENDING_DELETION`	409	The source is being deleted. It cannot be edited.
`SOURCE_ALREADY_PENDING_DELETION`	409	DELETE was called on a source that is already being deleted.
`SOURCE_LINK_LIMIT_EXCEEDED`	422	The 15 crawl/sitemap-parent limit per agent has been reached. Delete an existing crawl or sitemap source before adding another.
`SOURCE_SIZE_LIMIT_EXCEEDED`	422	Creating or updating this source would exceed the plan’s storage limit. Remove existing sources or upgrade your plan.
`SOURCE_DUPLICATE`	409	A link source with this URL and `linkType` already exists for this agent.
`SOURCE_URL_IMMUTABLE`	400	A link’s URL cannot be changed via PUT. Delete and recreate the source to use a different URL.

​Hostname routing

​Source types

​Source status

​Editing a source that is training

​Deletes are permanent

​File upload rate limit

​Endpoints