API reference

Bots API

Create, configure and embed assistants: generate one from a plain-language description or a scan of a website, rehearse it before it goes live, restore an earlier version, and fetch the snippet a site pastes in.

Endpoints

21 operations, each with its parameters, schemas and an example request on its own page.

get/api/botsList bots
post/api/botsCreate bot
post/api/bots/generateGenerate bot — Builds a fully-configured bot from one plain-language description.
get/api/bots/modelsAvailable models — Models this org's plan may select, with measured characteristics.
post/api/bots/onboarding/rehearseRehearse blueprint — Shows what a candidate assistant would say, before anything is live.
post/api/bots/onboarding/scanScan website — Reads a business's website, best pages first.
post/api/bots/onboarding/variantsGenerate variants — Three configurations to choose between.
get/api/bots/{bot_id}Get bot
patch/api/bots/{bot_id}Update bot
delete/api/bots/{bot_id}Delete bot — Soft delete: the bot goes offline immediately and is purged after the retention window, so an accidental…
post/api/bots/{bot_id}/duplicateDuplicate bot
get/api/bots/{bot_id}/embedGet embed — The snippet a customer pastes, in two forms.
get/api/bots/{bot_id}/funnelGet funnel — Impressions, opens and abandonment - the funnel above the first message.
post/api/bots/{bot_id}/rotate-keyRotate key — Issues a new embed key. Every existing embed of this bot stops working.
post/api/bots/{bot_id}/suggest-improvementsSuggest improvements — Reviews the questions this bot answered badly and proposes fixes.
post/api/bots/{bot_id}/testTest message — Sends one message through the same retrieval and generation path the widget uses, without creating a…
post/api/bots/{bot_id}/theme/avatarUpload avatar — Uploads the assistant's avatar and points the theme at it.
delete/api/bots/{bot_id}/theme/avatarDelete avatar — Removes the avatar and clears the theme field.
post/api/bots/{bot_id}/theme/generateGenerate theme — A palette from a sentence, or from the customer's own website.
get/api/bots/{bot_id}/versionsList versions
post/api/bots/{bot_id}/versions/{version}/restoreRestore version

Authentication

Every call here needs Authorization: Bearer with a key from the dashboard — Authentication covers keys and scopes.

Objects returned

The models these endpoints send back, with every field. Open one to read it.

PaginatedResponse_BotRead_6 fields

itemsarray of BotReadrequired
34 fields · BotRead
- allowed_domainsarray of string | nullrequired
- contact_fields_configarray of anyrequired
- created_atstring (date-time)required
- descriptionstring | nullrequired
- directory_configobject | nullrequired
- fallback_messagestring | nullrequired
- handoff_enabledbooleanrequired
- idstringrequired
- indexed_chunk_countintegerrequired
- is_publicbooleanrequired
- languagestringrequired
- last_errorstring | nullrequired
- lead_capture_configobject | nullrequired
- llm_providerLLMProviderTyperequired
  platform uses the credentials this deployment is configured with; byok ("bring your own key") uses the tenant's own Anthropic key; custom posts to an owner-supplied OpenAI-compatible endpoint.
  One of: platform, byok, custom
- max_tokensintegerrequired
- modelstring | nullrequired
- monthly_message_capinteger | nullrequired
- namestringrequired
- org_idstringrequired
- public_keystringrequired
- rate_limit_per_minuteintegerrequired
- starter_questionsarray of stringrequired
- statusBotStatusrequired
  One of: draft, active, paused, archived
- strict_kb_modebooleanrequired
- system_promptstringrequired
- temperaturenumberrequired
- thinking_enabledbooleanrequired
- total_conversationsintegerrequired
- total_messagesintegerrequired
- updated_atstring (date-time)required
- welcome_messagestring | nullrequired
- widget_themeobjectrequired
- custom_endpoint_configobject | null
- has_api_keyboolean
  Default: false
pageintegerrequired
page_sizeintegerrequired
totalintegerrequired
has_moreboolean
Default: false
next_cursorstring | null

BotRead34 fields

allowed_domainsarray of string | nullrequired
contact_fields_configarray of anyrequired
created_atstring (date-time)required
descriptionstring | nullrequired
directory_configobject | nullrequired
fallback_messagestring | nullrequired
handoff_enabledbooleanrequired
idstringrequired
indexed_chunk_countintegerrequired
is_publicbooleanrequired
languagestringrequired
last_errorstring | nullrequired
lead_capture_configobject | nullrequired
llm_providerLLMProviderTyperequired
platform uses the credentials this deployment is configured with; byok ("bring your own key") uses the tenant's own Anthropic key; custom posts to an owner-supplied OpenAI-compatible endpoint.
One of: platform, byok, custom
max_tokensintegerrequired
modelstring | nullrequired
monthly_message_capinteger | nullrequired
namestringrequired
org_idstringrequired
public_keystringrequired
rate_limit_per_minuteintegerrequired
starter_questionsarray of stringrequired
statusBotStatusrequired
One of: draft, active, paused, archived
strict_kb_modebooleanrequired
system_promptstringrequired
temperaturenumberrequired
thinking_enabledbooleanrequired
total_conversationsintegerrequired
total_messagesintegerrequired
updated_atstring (date-time)required
welcome_messagestring | nullrequired
widget_themeobjectrequired
custom_endpoint_configobject | null
has_api_keyboolean
Default: false

BotGenerateResponse4 fields

blueprintBotBlueprintrequired
The generated configuration, before it becomes a bot.
15 fields · BotBlueprint
- contact_fields_configarray of anyrequired
- descriptionstringrequired
- directory_configobject | nullrequired
- fallback_messagestringrequired
- industrystringrequired
- languagestringrequired
- lead_capture_configobject | nullrequired
- namestringrequired
- starter_questionsarray of stringrequired
- strict_kb_modebooleanrequired
- suggested_kb_topicsarray of stringrequired
- system_promptstringrequired
- temperaturenumberrequired
- welcome_messagestringrequired
- widget_themeobjectrequired
botBotRead | null
34 fields · BotRead
- allowed_domainsarray of string | nullrequired
- contact_fields_configarray of anyrequired
- created_atstring (date-time)required
- descriptionstring | nullrequired
- directory_configobject | nullrequired
- fallback_messagestring | nullrequired
- handoff_enabledbooleanrequired
- idstringrequired
- indexed_chunk_countintegerrequired
- is_publicbooleanrequired
- languagestringrequired
- last_errorstring | nullrequired
- lead_capture_configobject | nullrequired
- llm_providerLLMProviderTyperequired
  platform uses the credentials this deployment is configured with; byok ("bring your own key") uses the tenant's own Anthropic key; custom posts to an owner-supplied OpenAI-compatible endpoint.
  One of: platform, byok, custom
- max_tokensintegerrequired
- modelstring | nullrequired
- monthly_message_capinteger | nullrequired
- namestringrequired
- org_idstringrequired
- public_keystringrequired
- rate_limit_per_minuteintegerrequired
- starter_questionsarray of stringrequired
- statusBotStatusrequired
  One of: draft, active, paused, archived
- strict_kb_modebooleanrequired
- system_promptstringrequired
- temperaturenumberrequired
- thinking_enabledbooleanrequired
- total_conversationsintegerrequired
- total_messagesintegerrequired
- updated_atstring (date-time)required
- welcome_messagestring | nullrequired
- widget_themeobjectrequired
- custom_endpoint_configobject | null
- has_api_keyboolean
  Default: false
embed_snippetstring | null
import_job_queuedboolean
Default: false

Message2 fields

messagestringrequired
okboolean
Default: true

TestMessageResponse7 fields

contentstringrequired
cost_usdnumberrequired
input_tokensintegerrequired
latency_msintegerrequired
modelstringrequired
output_tokensintegerrequired
citationsarray of object

BotVersionRead4 fields

created_atstring (date-time)required
notestring | nullrequired
snapshotobjectrequired
versionintegerrequired

Something here wrong or missing? Tell us — the documentation and the API are maintained by the same person, so a correction is a fix rather than a ticket.