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

# BotSmith Sources API: Add Files, Websites, and Text

> Add files, websites, and text as training sources to your BotSmith agents using the REST API. Manage and delete sources programmatically.

The Sources API lets you add, list, and delete the training data that powers your agents. Sources include uploaded files, scraped websites, and plain text snippets. After you add a source, BotSmith processes it asynchronously — chunking, embedding, and storing it in the agent's knowledge base. All endpoints require authentication.

## List Sources for an Agent

**`GET /api/sources/chatbot/{chatbot_id}`**

Returns all training sources attached to the specified agent.

```bash theme={null}
curl -H "Authorization: Bearer TOKEN" \
  https://app.botsmith.ai/api/sources/chatbot/CHATBOT_ID
```

**Path parameters:**

<ParamField path="chatbot_id" type="string" required>
  The unique ID of the agent whose sources you want to list.
</ParamField>

**Response (`200 OK`):**

```json theme={null}
[
  {
    "id": "src_abc123",
    "chatbot_id": "bot_abc123",
    "type": "file",
    "name": "product-manual.pdf",
    "url": null,
    "file_type": "pdf",
    "file_size": 204800,
    "status": "completed",
    "error_message": null,
    "created_at": "2024-06-01T09:15:00Z"
  },
  {
    "id": "src_def456",
    "chatbot_id": "bot_abc123",
    "type": "website",
    "name": "https://example.com/faq",
    "url": "https://example.com/faq",
    "file_type": null,
    "file_size": null,
    "status": "completed",
    "error_message": null,
    "created_at": "2024-06-01T09:20:00Z"
  }
]
```

<ResponseField name="id" type="string">
  Unique identifier for the source.
</ResponseField>

<ResponseField name="type" type="string">
  Source type: `"file"`, `"website"`, or `"text"`.
</ResponseField>

<ResponseField name="name" type="string">
  Display name of the source — the original filename, URL, or text title.
</ResponseField>

<ResponseField name="url" type="string | null">
  The URL for website sources; `null` for file and text sources.
</ResponseField>

<ResponseField name="file_type" type="string | null">
  File extension for file sources (e.g., `"pdf"`, `"docx"`); `null` for website and text sources.
</ResponseField>

<ResponseField name="file_size" type="integer | null">
  File size in bytes for file sources; `null` for website and text sources.
</ResponseField>

<ResponseField name="status" type="string">
  Processing status: `"processing"`, `"completed"`, or `"failed"`.
</ResponseField>

<ResponseField name="error_message" type="string | null">
  If `status` is `"failed"`, this field contains a description of what went wrong.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the source was added.
</ResponseField>

***

## Upload a File Source

**`POST /api/sources/chatbot/{chatbot_id}/file`**

Uploads a file as a training source using `multipart/form-data`. The file is processed asynchronously — the response returns immediately with `status: "processing"`. Poll the [list sources](#list-sources-for-an-agent) endpoint to check when `status` changes to `"completed"`.

**Maximum file size:** 100 MB

```bash theme={null}
curl -X POST https://app.botsmith.ai/api/sources/chatbot/CHATBOT_ID/file \
  -H "Authorization: Bearer TOKEN" \
  -F "file=@/path/to/product-manual.pdf"
```

**Path parameters:**

<ParamField path="chatbot_id" type="string" required>
  The unique ID of the agent to attach the file to.
</ParamField>

**Form fields:**

<ParamField body="file" type="file" required>
  The file to upload. Supported formats: `.pdf`, `.docx`, `.txt`, `.xlsx`, `.csv`. Maximum size: 100 MB.
</ParamField>

**Response (`201 Created`):**

```json theme={null}
{
  "id": "src_abc123",
  "chatbot_id": "bot_abc123",
  "type": "file",
  "name": "product-manual.pdf",
  "url": null,
  "file_type": null,
  "file_size": null,
  "status": "processing",
  "error_message": null,
  "created_at": "2024-06-01T09:15:00Z"
}
```

<Note>
  File processing runs in the background. Check the source's `status` field — it moves from `"processing"` to `"completed"` (or `"failed"`) once BotSmith finishes indexing the content.
</Note>

***

## Add a Website Source

**`POST /api/sources/chatbot/{chatbot_id}/website`**

Scrapes a webpage and adds its content as a training source. Send the URL as a `multipart/form-data` field. Like file uploads, scraping runs asynchronously.

```bash theme={null}
curl -X POST https://app.botsmith.ai/api/sources/chatbot/CHATBOT_ID/website \
  -H "Authorization: Bearer TOKEN" \
  -F "url=https://example.com/faq"
```

**Path parameters:**

<ParamField path="chatbot_id" type="string" required>
  The unique ID of the agent to attach the website to.
</ParamField>

**Form fields:**

<ParamField body="url" type="string" required>
  The full URL to scrape (e.g., `https://example.com/faq`). Must be a publicly accessible page.
</ParamField>

**Response (`201 Created`):**

```json theme={null}
{
  "id": "src_def456",
  "chatbot_id": "bot_abc123",
  "type": "website",
  "name": "https://example.com/faq",
  "url": "https://example.com/faq",
  "file_type": null,
  "file_size": null,
  "status": "processing",
  "error_message": null,
  "created_at": "2024-06-01T09:20:00Z"
}
```

***

## Add a Text Source

**`POST /api/sources/chatbot/{chatbot_id}/text`**

Adds plain text directly as a training source using `multipart/form-data`. Unlike file and website sources, text sources are marked `"completed"` immediately because no external processing is needed.

```bash theme={null}
curl -X POST https://app.botsmith.ai/api/sources/chatbot/CHATBOT_ID/text \
  -H "Authorization: Bearer TOKEN" \
  -F "name=Product FAQ" \
  -F "content=Q: What is your return policy?
A: We offer a 30-day no-questions-asked return policy on all items."
```

**Path parameters:**

<ParamField path="chatbot_id" type="string" required>
  The unique ID of the agent to attach the text to.
</ParamField>

**Form fields:**

<ParamField body="name" type="string" required>
  A descriptive label for this text source (e.g., `"Product FAQ"`, `"Shipping Policy"`).
</ParamField>

<ParamField body="content" type="string" required>
  The raw text content to add to the knowledge base.
</ParamField>

**Response (`201 Created`):**

```json theme={null}
{
  "id": "src_ghi789",
  "chatbot_id": "bot_abc123",
  "type": "text",
  "name": "Product FAQ",
  "url": null,
  "file_type": null,
  "file_size": null,
  "status": "completed",
  "error_message": null,
  "created_at": "2024-06-01T09:25:00Z"
}
```

***

## Delete a Source

**`DELETE /api/sources/{source_id}`**

Permanently removes a training source and deletes its associated vectors from the agent's knowledge base. Returns `204 No Content` on success.

```bash theme={null}
curl -X DELETE \
  -H "Authorization: Bearer TOKEN" \
  https://app.botsmith.ai/api/sources/src_abc123
```

**Path parameters:**

<ParamField path="source_id" type="string" required>
  The unique ID of the source to delete.
</ParamField>

**Response:** `204 No Content` — no response body.

<Warning>
  Deleting a source removes its content from the agent's knowledge base immediately. The agent will no longer be able to answer questions based on that content.
</Warning>