BotSmith Sources API: Add Files, Websites, and Text

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.

curl -H "Authorization: Bearer TOKEN" \
  https://app.botsmith.ai/api/sources/chatbot/CHATBOT_ID

Path parameters:

string

required

The unique ID of the agent whose sources you want to list.

Response (200 OK):

[
  {
    "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"
  }
]

string

Unique identifier for the source.

string

Source type: "file", "website", or "text".

string

Display name of the source — the original filename, URL, or text title.

string | null

The URL for website sources; null for file and text sources.

string | null

File extension for file sources (e.g., "pdf", "docx"); null for website and text sources.

integer | null

File size in bytes for file sources; null for website and text sources.

string

Processing status: "processing", "completed", or "failed".

string | null

If status is "failed", this field contains a description of what went wrong.

string

ISO 8601 timestamp of when the source was added.

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 endpoint to check when status changes to "completed". Maximum file size: 100 MB

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:

string

required

The unique ID of the agent to attach the file to.

Form fields:

file

required

The file to upload. Supported formats: .pdf, .docx, .txt, .xlsx, .csv. Maximum size: 100 MB.

Response (201 Created):

{
  "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"
}

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.

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.

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:

string

required

The unique ID of the agent to attach the website to.

Form fields:

string

required

The full URL to scrape (e.g., https://example.com/faq). Must be a publicly accessible page.

Response (201 Created):

{
  "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.

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:

string

required

The unique ID of the agent to attach the text to.

Form fields:

string

required

A descriptive label for this text source (e.g., "Product FAQ", "Shipping Policy").

string

required

The raw text content to add to the knowledge base.

Response (201 Created):

{
  "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.

curl -X DELETE \
  -H "Authorization: Bearer TOKEN" \
  https://app.botsmith.ai/api/sources/src_abc123

Path parameters:

string

required

The unique ID of the source to delete.

Response: 204 No Content — no response body.

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.

Overview

Endpoints

BotSmith Sources API: Add Files, Websites, and Text

List Sources for an Agent

Upload a File Source

Add a Website Source

Add a Text Source

Delete a Source

​List Sources for an Agent

​Upload a File Source

​Add a Website Source

​Add a Text Source

​Delete a Source

List Sources for an Agent

Upload a File Source

Add a Website Source

Add a Text Source

Delete a Source