API reference · Bots

Generate bot

Builds a fully-configured bot from one plain-language description.

posthttps://api.integrable.cloud/api/bots/generate

Authentication: Bearer token
Retries: Idempotency-Key
Body: application/json
Version: 2026-09-03

This is the product's main path, not a convenience wrapper: the customer describes their business, and everything the advanced screens expose - persona, greeting, starter questions, which details to collect and when, what to extract from conversation, routing, theme - is inferred. They open the advanced screens only to disagree with something.

With import_website, the site is also crawled into the knowledge base in the background, so the bot can answer real questions from its first minute rather than being an empty persona.

Headers

Idempotency-Keystring
A unique key of your choosing, so this request can be retried safely. The first request with a given key executes; every replay returns that first response unchanged, with Idempotent-Replay: true set.
Generate one key per action, not per session - reusing a key with a different body is refused with 422 rather than silently replaying the wrong answer. Keys are remembered for 24 hours. A request that failed releases its key, so a retry after fixing the payload runs normally.
Up to 255 characters

Request body

application/json · required

BotGenerateRequest

descriptionstringrequired
What the business does, who it serves, and what the bot should do.
10–4000 characters
activateboolean
Default: false
import_websiteboolean
Default: true
website_urlstring | null
Optional. Read to match tone and seed the knowledge base.
Up to 1000 characters

Responses

200OKapplication/json
BotGenerateResponse
- 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
5 response headers
RateLimit-Limit
Requests permitted in the current window.
RateLimit-Remaining
Requests left in the current window. Back off before it reaches 0.
RateLimit-Reset
Seconds until the current window resets.
X-API-Version
The dated version of the API contract that served this response, e.g. 2026-09-03. Pin against it; it changes only when a response shape changes incompatibly.
X-Request-ID
Quote this in a support request to identify the call.
422Validation error
The shared error envelope, served as application/problem+json with error.code set to validation_error. Its details name each field that failed and why.

Example request

curl

curl -X POST "https://api.integrable.cloud/api/bots/generate" \
  -H "Authorization: Bearer $INTEGRABLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "string"
  }'

Set INTEGRABLE_API_KEY first. The same call from the TypeScript or Python SDK takes the same fields.

Example response

200 OK · application/json

{
  "blueprint": {
    "contact_fields_config": [
      "string"
    ],
    "description": "string",
    "directory_config": {},
    "fallback_message": "string",
    "industry": "string",
    "language": "string",
    "lead_capture_config": {},
    "name": "string",
    "starter_questions": [
      "string"
    ],
    "strict_kb_mode": true,
    "suggested_kb_topics": [
      "string"
    ],
    "system_prompt": "string",
    "temperature": 0,
    "welcome_message": "string",
    "widget_theme": {}
  },
  "bot": {
    "allowed_domains": [
      "https://example.com"
    ],
    "contact_fields_config": [
      "string"
    ],
    "created_at": "2026-09-03T09:30:00Z",
    "custom_endpoint_config": {},
    "description": "string",
    "directory_config": {},
    "fallback_message": "string",
    "handoff_enabled": true,
    "has_api_key": false,
    "id": "01a0652b-3713-7ea1-a6c9-2e895389ec34",
    "indexed_chunk_count": 20,
    "is_public": true,
    "language": "string",
    "last_error": "string",
    "lead_capture_config": {},
    "llm_provider": "platform",
    "max_tokens": 0,
    "model": "string",
    "monthly_message_cap": 0,
    "name": "string",
    "org_id": "01a0652b-3713-7ea1-a6c9-2e895389ec34",
    "public_key": "string",
    "rate_limit_per_minute": 20,
    "starter_questions": [
      "string"
    ],
    "status": "draft",
    "strict_kb_mode": true,
    "system_prompt": "string",
    "temperature": 0,
    "thinking_enabled": true,
    "total_conversations": 0,
    "total_messages": 0,
    "updated_at": "2026-09-03T09:30:00Z",
    "welcome_message": "string",
    "widget_theme": {}
  },
  "embed_snippet": "string",
  "import_job_queued": false
}

Generated from the schema above — the shape is exact, the values are placeholders.

Errors

Failures use one envelope on every endpoint, described in Retries, versioning and limits. The codes you are most likely to meet here:

validation_error · 422 — The payload was well-formed JSON but failed schema validation.
unauthenticated · 401 — The request carried no API key, or one the API could not verify.
forbidden · 403 — The key is valid, but it is not allowed to do this — either the scope is missing or the resource belongs to another workspace.
idempotency_key_reused · 422 — This `Idempotency-Key` was used before, for a request with a different body.
rate_limited · 429 — Too many requests in the current window. The limit is per workspace, and some endpoints add a per-bot limit on top.

More Bots endpoints

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.