Sources - Chatbase

The Sources API lets you manage the content your agent is trained on. You can list, inspect, create, update, delete, and restore sources without touching the dashboard.

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	Restore
`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 that reflects its position in the training lifecycle.

Status	Meaning
`untrained`	Newly created; not yet included in a training run
`trained`	Part of the agent’s active knowledge base
`updated`	Content changed since last training — retrain needed
`toBeDeletedted`	Marked for removal; will be removed on the next training run
`deleted`	Permanently removed. Only returned by the DELETE endpoint response; never appears in list or get results.

When Get sources summary returns shouldRetrain: true, at least one source has untrained, updated, or toBeDeletedted status. Retrain your agent from the dashboard to apply the changes.

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

Soft-delete with restore support

Restore source

Undo a pending deletion

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_PENDING_DELETION`	409	Source has `toBeDeletedted` status. Restore it before making edits.
`SOURCE_NOT_RESTORABLE`	409	Restore was called on a source that is not in `toBeDeletedted` state.
`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.