> ## 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 Agents API: Create, Update, and Delete Agents

> Create, retrieve, update, delete, and toggle BotSmith agents using the REST API. Includes request and response examples for each endpoint.

The Agents API lets you manage your AI agents programmatically. Use it to create agents, update their configuration, toggle their active status, and delete them. All endpoints require authentication.

## List All Agents

**`GET /api/chatbots`**

Returns all agents belonging to the authenticated user, including conversation counts for each.

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

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

```json theme={null}
[
  {
    "id": "abc123",
    "user_id": "user_001",
    "name": "Support Bot",
    "description": null,
    "model": "gpt-4o-mini",
    "provider": "openai",
    "temperature": 0.7,
    "max_tokens": 500,
    "status": "active",
    "public_access": true,
    "messages_count": 342,
    "conversations_count": 57,
    "primary_color": "#7c3aed",
    "secondary_color": "#ec4899",
    "accent_color": "#ec4899",
    "welcome_message": "Hi! I'm your AI assistant. How can I help you today?",
    "widget_position": "bottom-right",
    "widget_theme": "auto",
    "widget_size": "medium",
    "lead_capture_enabled": true,
    "created_at": "2024-03-15T10:00:00Z",
    "updated_at": "2024-06-01T09:00:00Z"
  }
]
```

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

<ResponseField name="name" type="string">
  The agent's display name.
</ResponseField>

<ResponseField name="description" type="string | null">
  Optional description of the agent's purpose.
</ResponseField>

<ResponseField name="model" type="string">
  The AI model the agent uses (e.g., `"gpt-4o-mini"`, `"gpt-4o"`).
</ResponseField>

<ResponseField name="provider" type="string">
  The AI provider: `"openai"`, `"anthropic"`, or `"google"`.
</ResponseField>

<ResponseField name="temperature" type="number">
  Response creativity setting between `0.0` (deterministic) and `1.0` (creative).
</ResponseField>

<ResponseField name="max_tokens" type="integer">
  Maximum number of tokens in the agent's response.
</ResponseField>

<ResponseField name="status" type="string">
  Agent status: `"active"` or `"inactive"`.
</ResponseField>

<ResponseField name="conversations_count" type="integer">
  Total number of conversations started with this agent.
</ResponseField>

<ResponseField name="messages_count" type="integer">
  Total number of messages exchanged with this agent.
</ResponseField>

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

***

## Create an Agent

**`POST /api/chatbots`**

Creates a new agent. Returns `201 Created` with the new agent object. Your plan determines how many agents you can create — a `403` response indicates you have reached your plan limit.

```bash theme={null}
curl -X POST https://app.botsmith.ai/api/chatbots \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "model": "gpt-4o-mini",
    "provider": "openai",
    "instructions": "You are a helpful support agent for Acme Corp.",
    "welcome_message": "Hi! How can I help you today?",
    "temperature": 0.7
  }'
```

**Request body:**

<ParamField body="name" type="string" required>
  The agent's display name. Shown in the dashboard and the chat widget.
</ParamField>

<ParamField body="model" type="string">
  The AI model to use. Common values: `"gpt-4o-mini"`, `"gpt-4o"`. Defaults to `"gpt-4o-mini"`.
</ParamField>

<ParamField body="provider" type="string">
  The AI provider: `"openai"` (default), `"anthropic"`, or `"google"`.
</ParamField>

<ParamField body="instructions" type="string">
  System prompt that defines the agent's persona and behaviour. Also accepted as `system_message`. If omitted, a default customer-support prompt is applied.
</ParamField>

<ParamField body="welcome_message" type="string">
  The first message shown when a chat window opens. Defaults to `"Hi! I'm your AI assistant. How can I help you today?"`.
</ParamField>

<ParamField body="temperature" type="number">
  Response creativity between `0.0` (deterministic) and `1.0` (creative). Defaults to `0.7`.
</ParamField>

<ParamField body="max_tokens" type="integer">
  Maximum number of tokens per response. Defaults to `500`.
</ParamField>

<ParamField body="description" type="string">
  Optional description of the agent's purpose.
</ParamField>

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

```json theme={null}
{
  "id": "abc123",
  "user_id": "user_001",
  "name": "Support Bot",
  "description": null,
  "model": "gpt-4o-mini",
  "provider": "openai",
  "temperature": 0.7,
  "max_tokens": 500,
  "system_message": "You are a helpful support agent for Acme Corp.",
  "instructions": "You are a helpful support agent for Acme Corp.",
  "status": "active",
  "public_access": true,
  "messages_count": 0,
  "conversations_count": 0,
  "primary_color": "#7c3aed",
  "secondary_color": "#ec4899",
  "accent_color": "#ec4899",
  "welcome_message": "Hi! How can I help you today?",
  "widget_position": "bottom-right",
  "widget_theme": "auto",
  "widget_size": "medium",
  "lead_capture_enabled": true,
  "created_at": "2024-06-01T09:00:00Z",
  "updated_at": "2024-06-01T09:00:00Z"
}
```

***

## Get an Agent

**`GET /api/chatbots/{chatbot_id}`**

Returns details for a single agent. Returns `404` if the agent does not exist or does not belong to your account.

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

**Path parameters:**

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

**Response:** Same structure as a single object from [List All Agents](#list-all-agents).

***

## Update an Agent

**`PUT /api/chatbots/{chatbot_id}`**

Updates one or more fields on an existing agent. Only include the fields you want to change — omitted fields remain unchanged.

```bash theme={null}
curl -X PUT https://app.botsmith.ai/api/chatbots/abc123 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot v2",
    "primary_color": "#6d28d9",
    "widget_position": "bottom-left"
  }'
```

**Path parameters:**

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

**Request body (all optional):**

<ParamField body="name" type="string">
  Updated display name.
</ParamField>

<ParamField body="description" type="string">
  Updated description.
</ParamField>

<ParamField body="model" type="string">
  Updated AI model (e.g., `"gpt-4o-mini"`, `"gpt-4o"`).
</ParamField>

<ParamField body="provider" type="string">
  Updated AI provider: `"openai"`, `"anthropic"`, or `"google"`.
</ParamField>

<ParamField body="instructions" type="string">
  Updated system prompt. Also accepted as `system_message`.
</ParamField>

<ParamField body="welcome_message" type="string">
  Updated welcome message shown when the chat widget opens.
</ParamField>

<ParamField body="temperature" type="number">
  Updated temperature value between `0.0` and `1.0`.
</ParamField>

<ParamField body="max_tokens" type="integer">
  Updated maximum tokens per response.
</ParamField>

<ParamField body="status" type="string">
  Set to `"active"` or `"inactive"` to manually change the agent's state. Use [Toggle](#toggle-agent-status) for a simple flip.
</ParamField>

<ParamField body="public_access" type="boolean">
  Whether the agent is publicly accessible via the widget. Set to `false` to restrict access.
</ParamField>

<ParamField body="primary_color" type="string">
  Primary hex color for the chat widget (e.g., `"#7c3aed"`).
</ParamField>

<ParamField body="secondary_color" type="string">
  Secondary hex color for the chat widget.
</ParamField>

<ParamField body="accent_color" type="string">
  Accent hex color for the chat widget.
</ParamField>

<ParamField body="widget_position" type="string">
  Widget position on the page: `"bottom-right"`, `"bottom-left"`, `"top-right"`, or `"top-left"`.
</ParamField>

<ParamField body="widget_theme" type="string">
  Widget color theme: `"light"`, `"dark"`, or `"auto"`.
</ParamField>

<ParamField body="widget_size" type="string">
  Widget size: `"small"`, `"medium"`, or `"large"`.
</ParamField>

<ParamField body="lead_capture_enabled" type="boolean">
  Whether the widget shows a lead capture form before the first message.
</ParamField>

<ParamField body="email_alerts_enabled" type="boolean">
  Whether email alerts are sent when a new lead is captured.
</ParamField>

<ParamField body="email_alert_address" type="string">
  Email address to receive lead capture alerts. Required if `email_alerts_enabled` is `true`.
</ParamField>

<ParamField body="rate_limit_enabled" type="boolean">
  Whether per-session rate limiting is enabled on the widget.
</ParamField>

<ParamField body="messages_per_hour" type="integer">
  Maximum messages a single session can send per hour when `rate_limit_enabled` is `true`. Defaults to `60`.
</ParamField>

**Response (`200 OK`):** The updated agent object (same structure as the create response).

***

## Delete an Agent

**`DELETE /api/chatbots/{chatbot_id}`**

Permanently deletes an agent and all associated data — sources, conversations, and messages. Returns `204 No Content` on success.

<Warning>
  This action is irreversible. Deleting an agent removes all of its training sources, conversations, and message history.
</Warning>

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

**Path parameters:**

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

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

***

## Toggle Agent Status

**`PATCH /api/chatbots/{chatbot_id}/toggle`**

Flips the agent's status between `"active"` and `"inactive"`. When an agent is `"inactive"`, the public chat endpoint returns a `400` error, preventing end-users from chatting with it.

```bash theme={null}
curl -X PATCH \
  -H "Authorization: Bearer TOKEN" \
  https://app.botsmith.ai/api/chatbots/abc123/toggle
```

**Path parameters:**

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

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

```json theme={null}
{
  "id": "abc123",
  "name": "Support Bot",
  "status": "inactive",
  "updated_at": "2024-06-01T10:30:00Z"
}
```

<ResponseField name="status" type="string">
  The new status after toggling: `"active"` or `"inactive"`.
</ResponseField>