BotSmith Agents API: Create, Update, and Delete Agents

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.

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

Response (200 OK):

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

string

Unique identifier for the agent.

string

The agent’s display name.

string | null

Optional description of the agent’s purpose.

string

The AI model the agent uses (e.g., "gpt-4o-mini", "gpt-4o").

string

The AI provider: "openai", "anthropic", or "google".

number

Response creativity setting between 0.0 (deterministic) and 1.0 (creative).

integer

Maximum number of tokens in the agent’s response.

string

Agent status: "active" or "inactive".

integer

Total number of conversations started with this agent.

integer

Total number of messages exchanged with this agent.

string

ISO 8601 timestamp of when the agent was created.

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.

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:

string

required

The agent’s display name. Shown in the dashboard and the chat widget.

string

The AI model to use. Common values: "gpt-4o-mini", "gpt-4o". Defaults to "gpt-4o-mini".

string

The AI provider: "openai" (default), "anthropic", or "google".

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.

string

The first message shown when a chat window opens. Defaults to "Hi! I'm your AI assistant. How can I help you today?".

number

Response creativity between 0.0 (deterministic) and 1.0 (creative). Defaults to 0.7.

integer

Maximum number of tokens per response. Defaults to 500.

string

Optional description of the agent’s purpose.

Response (201 Created):

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

curl -H "Authorization: Bearer TOKEN" \
  https://app.botsmith.ai/api/chatbots/abc123

Path parameters:

string

required

The unique ID of the agent to retrieve.

Response: Same structure as a single object from 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.

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:

string

required

The unique ID of the agent to update.

Request body (all optional):

string

Updated display name.

string

Updated description.

string

Updated AI model (e.g., "gpt-4o-mini", "gpt-4o").

string

Updated AI provider: "openai", "anthropic", or "google".

string

Updated system prompt. Also accepted as system_message.

string

Updated welcome message shown when the chat widget opens.

number

Updated temperature value between 0.0 and 1.0.

integer

Updated maximum tokens per response.

string

Set to "active" or "inactive" to manually change the agent’s state. Use Toggle for a simple flip.

boolean

Whether the agent is publicly accessible via the widget. Set to false to restrict access.

string

Primary hex color for the chat widget (e.g., "#7c3aed").

string

Secondary hex color for the chat widget.

string

Accent hex color for the chat widget.

Widget position on the page: "bottom-right", "bottom-left", "top-right", or "top-left".

Widget color theme: "light", "dark", or "auto".

Widget size: "small", "medium", or "large".

boolean

Whether the widget shows a lead capture form before the first message.

boolean

Whether email alerts are sent when a new lead is captured.

string

Email address to receive lead capture alerts. Required if email_alerts_enabled is true.

boolean

Whether per-session rate limiting is enabled on the widget.

integer

Maximum messages a single session can send per hour when rate_limit_enabled is true. Defaults to 60.

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.

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

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

Path parameters:

string

required

The unique ID of the agent to delete.

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.

curl -X PATCH \
  -H "Authorization: Bearer TOKEN" \
  https://app.botsmith.ai/api/chatbots/abc123/toggle

Path parameters:

string

required

The unique ID of the agent to toggle.

Response (200 OK):

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

string

The new status after toggling: "active" or "inactive".

Overview

Endpoints

BotSmith Agents API: Create, Update, and Delete Agents

List All Agents

Create an Agent

Get an Agent

Update an Agent

Delete an Agent

Toggle Agent Status

​List All Agents

​Create an Agent

​Get an Agent

​Update an Agent

​Delete an Agent

​Toggle Agent Status

List All Agents

Create an Agent

Get an Agent

Update an Agent

Delete an Agent

Toggle Agent Status