Manage Bots

Every endpoint on this page requires an OAuth2 access token (chatty_oat_...), not an API key. An API key is scoped to one bot and has no concept of "your account" — creating or listing bots needs a principal that spans your whole account. GET/PATCH .../{bot_id} and the analytics/knowledge endpoints also accept an API key, but only for the one bot that key was minted for.

Create a bot

POST/api/v1/bots

Required scope: write (OAuth2 only)

namestringbodyrequired

Display name for the new bot.

welcome_messagestringbody

First message visitors see. Defaults to a generic greeting.

system_instructionsstringbody

The bot's system prompt — persona, rules, knowledge boundaries.

selected_modelstringbody

LLM model id. Omit for the account default.

primary_colorstringbody

Hex color for the widget accent, e.g. "#f97316".

response_languagestringbody

Language code the bot should reply in, e.g. "en".

cURL

curl -X POST https://api.chatty.personaliai.com/api/v1/bots \
  -H "Authorization: Bearer chatty_oat_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support Bot", "welcome_message": "Hi! How can I help?"}'

List your bots

GET/api/v1/bots

Required scope: read (OAuth2 only)

Returns every bot your account owns: id, name, welcome_message, primary_color, selected_model, created_at.

Get a bot

GET/api/v1/bots/{bot_id}

Required scope: read

idstring

Bot id.

namestring

Display name.

welcome_messagestring

First message.

primary_colorstring

Hex accent color.

selected_modelstring

LLM model id.

system_instructionsstring

System prompt.

widget_stylestring

Design preset id.

response_languagestring

Forced reply language, or empty for auto-mirror.

strict_modeboolean

Whether the bot only answers from its knowledge base.

lead_capture_enabledboolean

Whether the bot captures visitor contact details.

created_atstring

ISO 8601 creation timestamp.

updated_atstring

ISO 8601 last-update timestamp.

Update a bot

PATCH/api/v1/bots/{bot_id}

Required scope: write

Same body fields as Create a bot, plus widget_style, strict_mode, and lead_capture_enabled. Only the fields you send are changed.

cURL

curl -X PATCH https://api.chatty.personaliai.com/api/v1/bots/BOT_ID \
  -H "Authorization: Bearer chatty_oat_your_token" \
  -H "Content-Type: application/json" \
  -d '{"primary_color": "#6366f1"}'

Add a knowledge source

POST/api/v1/bots/{bot_id}/knowledge

Required scope: write

namestringbodyrequired

Display name for the source.

contentstringbodyrequired

Text content (max 100,000 characters). For URL crawling, use the per-key Add Knowledge Source endpoint instead.

Analyze a bot

GET/api/v1/bots/{bot_id}/analytics

Required scope: read

total_messagesinteger

Total conversation messages, all time.

user_messagesinteger

Messages sent by visitors.

bot_messagesinteger

Messages sent by the assistant.

unique_sessionsinteger

Distinct visitor sessions.

total_leadsinteger

Leads captured, all time.

For a single bot you already have an API key for, GET /api/v1/analytics supports a since filter this endpoint doesn't yet have.

Get Bot Details

List Leads