> ## 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 REST API: Overview and Getting Started Guide

> The BotSmith REST API lets you programmatically create agents, add training sources, send chat messages, and retrieve analytics from your own applications.

The BotSmith REST API gives you programmatic access to everything you can do in the dashboard — create and manage agents, add training sources, send chat messages, and pull analytics data. All requests use JSON and standard HTTP methods.

## Base URL

All API endpoints are relative to:

```text theme={null}
https://app.botsmith.ai/api
```

## Authentication

All requests (except public chat and public lead endpoints) require a Bearer token in the `Authorization` header:

```text theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

Obtain a token by calling the login endpoint. See [Authentication](/api-reference/authentication) for full details.

## Request Format

* **JSON requests** — set `Content-Type: application/json` and send a JSON body.
* **File uploads and form data** — set `Content-Type: multipart/form-data` and send a form with the required fields.

```bash theme={null}
# JSON request example
curl -X POST https://app.botsmith.ai/api/chatbots \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support Bot", "model": "gpt-4o-mini"}'
```

## Response Format

All responses return JSON. Successful responses use `2xx` status codes. Error responses return a JSON object with a `detail` field describing the problem:

```json theme={null}
{
  "detail": "Chatbot not found"
}
```

For validation or plan-limit errors the `detail` field may be a structured object:

```json theme={null}
{
  "detail": {
    "message": "Chatbot limit reached for your plan",
    "current": 3,
    "max": 3,
    "upgrade_required": true
  }
}
```

## Rate Limits

API rate limits depend on your BotSmith plan. Default limits are:

| Window     | Limit          |
| ---------- | -------------- |
| Per minute | 60 requests    |
| Per hour   | 1,000 requests |

When you exceed the rate limit the API returns a `429 Too Many Requests` response. Wait until the window resets before retrying.

## Error Codes

| Status | Meaning                                                                      |
| ------ | ---------------------------------------------------------------------------- |
| `200`  | **OK** — request succeeded                                                   |
| `201`  | **Created** — resource created successfully                                  |
| `204`  | **No Content** — deletion succeeded, no body returned                        |
| `400`  | **Bad Request** — invalid parameters or malformed request body               |
| `401`  | **Unauthorized** — missing or invalid Bearer token                           |
| `402`  | **Payment Required** — subscription expired or payment failed                |
| `403`  | **Forbidden** — plan limit reached or insufficient permissions               |
| `404`  | **Not Found** — the requested resource does not exist                        |
| `429`  | **Too Many Requests** — rate limit or message quota exceeded                 |
| `500`  | **Internal Server Error** — something went wrong on our end; try again later |

## Pagination

List endpoints (for example, `GET /api/chatbots` or `GET /api/leads`) return all matching resources as a JSON array in a single response. There is no cursor or page token required for standard list calls.

```json theme={null}
[
  { "id": "abc123", "name": "Support Bot" },
  { "id": "def456", "name": "Sales Bot" }
]
```