> ## Documentation Index
> Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sources

> Programmatically manage the knowledge sources that power your Chatbase agent — web pages, documents, Q&A pairs, and text.

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

<Warning>
  **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.
</Warning>

## 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](/api-v2/sources/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

<CardGroup cols={2}>
  <Card title="List sources" icon="list" href="/api-v2/sources/list-sources">
    Paginated list with optional type and name filters
  </Card>

  <Card title="Sources summary" icon="chart-bar" href="/api-v2/sources/get-sources-summary">
    Aggregate counts and sizes per source type
  </Card>

  <Card title="Get source" icon="magnifying-glass" href="/api-v2/sources/get-source">
    Retrieve a single source by ID
  </Card>

  <Card title="Create source" icon="plus" href="/api-v2/sources/create-source">
    Create text, Q\&A, and link sources
  </Card>

  <Card title="Create file source" icon="file-arrow-up" href="/api-v2/sources/create-file-source">
    Upload PDF, DOCX, or TXT files
  </Card>

  <Card title="Update source" icon="pen" href="/api-v2/sources/update-source">
    Update text, Q\&A, and link sources
  </Card>

  <Card title="Update file source" icon="file-pen" href="/api-v2/sources/update-file-source">
    Replace file content or rename a file source
  </Card>

  <Card title="Delete source" icon="trash" href="/api-v2/sources/delete-source">
    Soft-delete with restore support
  </Card>

  <Card title="Restore source" icon="rotate-left" href="/api-v2/sources/restore-source">
    Undo a pending deletion
  </Card>
</CardGroup>

## Error codes

Sources-specific error codes beyond the standard [authentication and rate-limiting errors](/api-v2/error-handling):

<table>
  <thead>
    <tr>
      <th style={{ whiteSpace: 'nowrap' }}>Code</th>
      <th>HTTP</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr><td style={{ whiteSpace: 'nowrap' }}><code>SOURCE\_NOT\_FOUND</code></td><td>404</td><td>Source doesn't exist, belongs to a different agent, or has been permanently deleted.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}><code>SOURCE\_TYPE\_NOT\_SUPPORTED</code></td><td>400</td><td>Attempting to update a <code>notionPage</code> via PUT. Manage Notion sources through the dashboard.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}><code>SOURCE\_PENDING\_DELETION</code></td><td>409</td><td>Source has <code>toBeDeletedted</code> status. <a href="/api-v2/sources/restore-source">Restore it</a> before making edits.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}><code>SOURCE\_NOT\_RESTORABLE</code></td><td>409</td><td>Restore was called on a source that is not in <code>toBeDeletedted</code> state.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}><code>SOURCE\_LINK\_LIMIT\_EXCEEDED</code></td><td>422</td><td>The 15 crawl/sitemap-parent limit per agent has been reached. Delete an existing crawl or sitemap source before adding another.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}><code>SOURCE\_SIZE\_LIMIT\_EXCEEDED</code></td><td>422</td><td>Creating or updating this source would exceed the plan's storage limit. Remove existing sources or upgrade your plan.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}><code>SOURCE\_DUPLICATE</code></td><td>409</td><td>A link source with this URL and <code>linkType</code> already exists for this agent.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}><code>SOURCE\_URL\_IMMUTABLE</code></td><td>400</td><td>A link's URL cannot be changed via PUT. Delete and recreate the source to use a different URL.</td></tr>
  </tbody>
</table>