API reference · Bots

Create bot

post/api/bots
Authentication
Bearer token
Retries
Idempotency-Key
Body
application/json
Version
2026-09-03

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

BotCreate

  • namestringrequired

    1–255 characters

  • allowed_domainsarray of string | null

    Up to 50 items

  • api_keystring | null

    Up to 500 characters

  • contact_fields_configarray of ContactFieldDef

    Up to 20 items

    4 fields · ContactFieldDef
    • keystringrequired

      1–40 characters·Pattern: ^[a-z][a-z0-9_]*$

    • labelstringrequired

      1–100 characters

    • optionsarray of string | null

      Up to 30 items

    • typestring

      One of: text, email, phone, select, number·Default: text

  • custom_endpoint_configCustomEndpointConfig | null
    5 fields · CustomEndpointConfig
    • endpoint_urlstringrequired

      8–1000 characters

    • auth_header_namestring | null

      Up to 100 characters

    • auth_header_valuestring | null

      Up to 2000 characters

    • modelstring | null

      Up to 128 characters

    • response_pathstring | null

      Up to 200 characters

  • descriptionstring | null

    Up to 2000 characters

  • directory_configDirectoryConfig | null

    Generic routing table: category + choice resolves to a link.

    Replaces the previous hard-coded doctors_config. A clinic reads it as branch/doctor/appointment link, a dealership as city/showroom/booking link, a university as campus/department/enquiry form - same code, no per-vertical branches.

    7 fields · DirectoryConfig
    • category_fieldstring

      Default: branch·Up to 40 characters

    • category_labelstring

      Default: Location·Up to 60 characters

    • choice_fieldstring

      Default: preferred_specialist·Up to 40 characters

    • choice_labelstring

      Default: Specialist·Up to 60 characters

    • enabledboolean

      Default: false

    • entriesarray of DirectoryEntry

      Up to 500 items

      4 fields · DirectoryEntry
      • namestringrequired

        1–150 characters

      • categorystring

        Default: ·Up to 100 characters

      • linkstring

        Default: ·Up to 1000 characters

      • metadataobject
    • result_fieldstring

      Default: booking_link·Up to 40 characters

  • fallback_messagestring | null

    Up to 1000 characters

  • handoff_configobject | null
  • handoff_enabledboolean

    Default: false

  • is_publicboolean

    Default: true

  • languagestring

    Default: auto·Up to 16 characters

  • lead_capture_configLeadCaptureConfig | null
    6 fields · LeadCaptureConfig
    • enabledboolean

      Default: false

    • fieldsarray of LeadCaptureField

      Up to 10 items

      5 fields · LeadCaptureField
      • keystringrequired

        1–40 characters·Pattern: ^[a-z][a-z0-9_]*$

      • labelstringrequired

        1–100 characters

      • placeholderstring | null

        Up to 120 characters

      • requiredboolean

        Default: false

      • typestring

        One of: text, email, phone, select, number·Default: text

    • introstring | null

      Up to 300 characters

    • titlestring | null

      Up to 120 characters

    • triggerstring

      One of: before_chat, after_n_messages, manual·Default: manual

    • trigger_valueinteger | null

      Default: 2·≥ 1 and ≤ 50

  • llm_providerLLMProviderType

    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·Default: platform

  • max_tokensinteger

    Default: 1024·≥ 64 and ≤ 32768

  • modelstring | null

    Up to 128 characters

  • monthly_message_capinteger | null

    ≥ 0

  • rate_limit_per_minuteinteger

    Default: 30·≥ 1 and ≤ 1000

  • starter_questionsarray of string

    Up to 6 items

  • strict_kb_modeboolean

    Default: false

  • system_promptstring | null

    Up to 20000 characters

  • temperaturenumber

    Default: 0.7·≥ 0 and ≤ 2

  • thinking_budget_tokensinteger

    Default: 2048·≥ 1024 and ≤ 32000

  • thinking_enabledboolean

    Default: false

  • welcome_messagestring | null

    Up to 1000 characters

  • widget_themeWidgetTheme

    Widget appearance. Extra keys are kept so the dashboard can add controls without a migration; the widget ignores what it does not recognise.

    -------------------------------------------------------------------- Contrast is enforced, and enforced differently for the two callers --------------------------------------------------------------------

    A tenant editing colours by hand is rejected, with the measured ratio and a hex that would pass, because they can see the result and are entitled to choose which colour moves.

    A theme produced by the one-prompt generator is repaired before it reaches this class - see generation_service._readable_theme. Failing an entire bot generation because a model picked a hex nobody asked for, and which the customer will never see, would be an absurd way to lose a signup.

    Two policies, one definition of readable, which is why the definition lives in app.platform.contrast and not here.

    39 fields · WidgetTheme
    • accent_colorstring | null

      Pattern: ^#[0-9A-Fa-f]{6}$

    • avatar_urlstring | null

      Up to 1000 characters

    • border_colorstring

      Default: #E2E8F0·Pattern: ^#[0-9A-Fa-f]{6}$

    • bot_bubble_bgstring

      Default: #FFFFFF·Pattern: ^#[0-9A-Fa-f]{6}$

    • bot_bubble_textstring

      Default: #0F172A·Pattern: ^#[0-9A-Fa-f]{6}$

    • bubble_radiusinteger

      Default: 16·≥ 0 and ≤ 28

    • bubble_radius_cornersarray of integer | null

      4–4 items

    • bubble_textstring | null

      Up to 100 characters

    • custom_cssstring | null

      Up to 8000 characters

    • darkDarkPalette | null

      The second palette, used when the visitor's system is set to dark.

      Not the tenant's preference - the visitor's. A tenant previewing on a light laptop is not the person the choice is for, and a widget that stays bright white on a dark site reads as broken rather than as branded.

      Every field is optional. A tenant who sets none gets a palette derived from their light one at render time, which is a better default than forcing them through a second colour picker they did not ask for.

      7 fields · DarkPalette
      • border_colorstring | null

        Pattern: ^#[0-9A-Fa-f]{6}$

      • bot_bubble_bgstring | null

        Pattern: ^#[0-9A-Fa-f]{6}$

      • bot_bubble_textstring | null

        Pattern: ^#[0-9A-Fa-f]{6}$

      • messages_bgstring | null

        Pattern: ^#[0-9A-Fa-f]{6}$

      • panel_bgstring | null

        Pattern: ^#[0-9A-Fa-f]{6}$

      • primary_colorstring | null

        Pattern: ^#[0-9A-Fa-f]{6}$

      • user_bubble_textstring | null

        Pattern: ^#[0-9A-Fa-f]{6}$

    • fontstring | null

      Default: system

    • header_subtitlestring | null

      Up to 100 characters

    • header_textstring

      Default: #FFFFFF·Pattern: ^#[0-9A-Fa-f]{6}$

    • header_titlestring | null

      Up to 60 characters

    • inline_targetstring | null

      Up to 100 characters

    • launcher_animationstring

      One of: none, fade, rise, pulse·Default: fade

    • launcher_labelstring | null

      Up to 28 characters

    • launcher_shapestring

      One of: circle, rounded, square·Default: circle

    • launcher_sizestring

      One of: sm, md, lg·Default: md

    • launcher_stylestring

      One of: icon, pill·Default: icon

    • layoutstring

      One of: floating, sidebar, inline, fullscreen·Default: floating

    • messages_bgstring

      Default: #F8FAFC·Pattern: ^#[0-9A-Fa-f]{6}$

    • offset_xinteger

      Default: 20·≥ 0 and ≤ 120

    • offset_yinteger

      Default: 20·≥ 0 and ≤ 120

    • panel_bgstring

      Default: #FFFFFF·Pattern: ^#[0-9A-Fa-f]{6}$

    • panel_heightinteger

      Default: 640·≥ 360 and ≤ 900

    • panel_radiusinteger

      Default: 20·≥ 0 and ≤ 32

    • panel_widthinteger

      Default: 380·≥ 300 and ≤ 520

    • positionstring

      One of: bottom-right, bottom-left·Default: bottom-right

    • primary_colorstring

      Default: #4F46E5·Pattern: ^#[0-9A-Fa-f]{6}$

    • primary_gradientGradient | null

      A two-stop linear gradient for the launcher and header.

      3 fields · Gradient
      • from_colorstringrequired

        Pattern: ^#[0-9A-Fa-f]{6}$

      • to_colorstringrequired

        Pattern: ^#[0-9A-Fa-f]{6}$

      • angleinteger

        Default: 135·≥ 0 and ≤ 360

    • proactivearray of ProactiveTrigger

      Up to 5 items

      5 fields · ProactiveTrigger
      • messagestringrequired

        1–300 characters

      • typestringrequired

        One of: time_on_page, exit_intent, scroll_depth, url_pattern, return_visitor, idle

      • open_panelboolean

        Default: false

      • thresholdinteger | null

        ≥ 1 and ≤ 3600

      • url_patternstring | null

        Up to 200 characters

    • proactive_cooldown_daysinteger

      Default: 7·≥ 0 and ≤ 90

    • show_brandingboolean

      Default: true

    • show_citationsboolean

      Default: true

    • theme_modestring

      One of: auto, light, dark·Default: auto

    • theme_versioninteger

      Default: 2·≥ 1 and ≤ 99

    • typing_indicatorstring

      One of: dots, pulse, wave, none·Default: dots

    • user_bubble_textstring

      Default: #FFFFFF·Pattern: ^#[0-9A-Fa-f]{6}$

Responses

  • 201Createdapplication/json

    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

    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" \
  -H "Authorization: Bearer $INTEGRABLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string"
  }'

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

Example response

201 Created · application/json
{
  "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": {}
}

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.

Building on it? Start on the free plan — no card — and call the same API the dashboard uses.

Start free