BotSmith REST API: Overview and Getting Started Guide

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:

https://app.botsmith.ai/api

Authentication

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

Authorization: Bearer YOUR_ACCESS_TOKEN

Obtain a token by calling the login endpoint. See 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.

# 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:

{
  "detail": "Chatbot not found"
}

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

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

[
  { "id": "abc123", "name": "Support Bot" },
  { "id": "def456", "name": "Sales Bot" }
]

​Base URL

​Authentication

​Request Format

​Response Format

​Rate Limits

​Error Codes

​Pagination