Update agent

patchhttps://api.integrable.cloud/api/agents/{agent_id}

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

Path parameters#

agent_idstringrequired

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

AgentUpdate

allowed_domainsarray of string | null
Up to 50 items
api_keystring | null
Up to 500 characters
contact_fields_configarray of ContactFieldDef | null
Up to 20 items
4 fieldsContactFieldDef
- 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 fieldsCustomEndpointConfig
- 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 fieldsDirectoryConfig
- 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 fieldsDirectoryEntry
  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
field_discoveryboolean | null
handoff_configobject | null
handoff_enabledboolean | null
is_publicboolean | null
languagestring | null
Up to 16 characters
language_configLanguageConfig | null
How an agent handles more than one language. Defaults are the behaviour of an agent that never opened the settings: follow the page, follow the visitor, every language, greetings translated automatically.
5 fieldsLanguageConfig
- auto_translateboolean
  Default: true
- detect_pageboolean
  Default: true
- follow_visitorboolean
  Default: true
- supportedarray of string
  Up to 40 items
- translationsmap of GreetingTranslation
  4 fieldsGreetingTranslation
  editedboolean
  Default: false
  sourcestring | null
  Up to 32 characters
  starter_questionsarray of string
  Up to 6 items
  welcome_messagestring | null
  Up to 1000 characters
lead_capture_configLeadCaptureConfig | null
7 fieldsLeadCaptureConfig
- ask_in_chatboolean
  Default: true
- enabledboolean
  Default: false
- fieldsarray of LeadCaptureField
  Up to 10 items
  5 fieldsLeadCaptureField
  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 | null
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_tokensinteger | null
≥ 64 and ≤ 32768
modelstring | null
Up to 128 characters
monthly_message_capinteger | null
≥ 0
namestring | null
1–255 characters
rate_limit_per_minuteinteger | null
≥ 1 and ≤ 1000
starter_questionsarray of string | null
Up to 6 items
statusAgentStatus | null
One of: draft, active, paused, archived
strict_kb_modeboolean | null
system_promptstring | null
Up to 20000 characters
temperaturenumber | null
≥ 0 and ≤ 2
thinking_budget_tokensinteger | null
≥ 1024 and ≤ 32000
thinking_enabledboolean | null
welcome_messagestring | null
Up to 1000 characters
widget_themeWidgetTheme | null
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 agent 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.
74 fieldsWidgetTheme
- accent_colorstring | null
  Pattern: ^#[0-9A-Fa-f]{6}$
- agent_bubble_bgstring
  Default: #FFFFFF·Pattern: ^#[0-9A-Fa-f]{6}$
- agent_bubble_stylestring
  One of: soft, flat, outline, glass, tail·Default: soft
- agent_bubble_textstring
  Default: #0F172A·Pattern: ^#[0-9A-Fa-f]{6}$
- agent_bubble_tintboolean
  Default: true
- avatar_urlstring | null
  Up to 1000 characters
- border_colorstring
  Default: #E2E8F0·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
- composer_stylestring
  One of: pill, rounded, inset, flat·Default: rounded
- 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 fieldsDarkPalette
  agent_bubble_bgstring | null
  Pattern: ^#[0-9A-Fa-f]{6}$
  agent_bubble_textstring | null
  Pattern: ^#[0-9A-Fa-f]{6}$
  border_colorstring | 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_bgstring | null
  Pattern: ^#[0-9A-Fa-f]{6}$
- header_gradientGradient | null
  A two-stop linear gradient for the launcher and header.
  3 fieldsGradient
  from_colorstringrequired
  Pattern: ^#[0-9A-Fa-f]{6}$
  to_colorstringrequired
  Pattern: ^#[0-9A-Fa-f]{6}$
  angleinteger
  Default: 135·≥ 0 and ≤ 360
- header_headlinestring | null
  Up to 60 characters
- header_highlightstring | null
  Up to 40 characters
- header_link_labelstring | null
  Up to 48 characters
- header_link_urlstring | null
  Up to 500 characters
- header_patternstring
  One of: none, dots, grid, rings, noise·Default: none
- header_subtitlestring | null
  Up to 100 characters
- header_textstring
  Default: #FFFFFF·Pattern: ^#[0-9A-Fa-f]{6}$
- header_titlestring | null
  Up to 60 characters
- header_variantstring
  One of: bar, hero, cover, minimal·Default: bar
- inline_targetstring | null
  Up to 100 characters
- launcher_animationstring
  One of: none, fade, rise, pulse·Default: fade
- launcher_ctastring | null
  Up to 24 characters
- launcher_effectstring
  One of: solid, light, glass·Default: solid
- launcher_gradientGradient | null
  A two-stop linear gradient for the launcher and header.
  3 fieldsGradient
  from_colorstringrequired
  Pattern: ^#[0-9A-Fa-f]{6}$
  to_colorstringrequired
  Pattern: ^#[0-9A-Fa-f]{6}$
  angleinteger
  Default: 135·≥ 0 and ≤ 360
- launcher_iconstring | null
  Up to 16 characters
- launcher_image_urlstring | null
  Up to 1000 characters
- launcher_labelstring | null
  Up to 40 characters
- launcher_ringboolean
  Default: false
- launcher_shapestring
  One of: circle, rounded, square, squircle, pill, cylinder, blob, teardrop, emoji·Default: circle
- launcher_sizestring
  One of: sm, md, lg·Default: md
- launcher_stylestring
  One of: icon, pill, bar, tab, dot, banner, card, ribbon, side·Default: icon
- launcher_subtitlestring | null
  Up to 90 characters
- launcher_teaserstring | null
  Up to 140 characters
- launcher_teaser_delayinteger
  Default: 2·≥ 0 and ≤ 60
- launcher_teaser_stylestring
  One of: bubble, message, tooltip·Default: bubble
- launcher_teaser_triggerstring
  One of: auto, hover·Default: auto
- layoutstring
  One of: floating, sidebar, modal, spotlight, sheet, inline, fullscreen·Default: floating
- message_densitystring
  One of: comfortable, compact·Default: comfortable
- messages_bgstring
  Default: #F8FAFC·Pattern: ^#[0-9A-Fa-f]{6}$
- offset_xinteger
  Default: 20·≥ 0 and ≤ 200
- offset_yinteger
  Default: 20·≥ 0 and ≤ 200
- 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, bottom-center, middle-right, middle-left, top-center·Default: bottom-right
- presetstring
  Default: classic·Up to 32 characters
- preset_downgraded_fromstring | null
  Up to 32 characters
- primary_colorstring
  Default: #0A0A0A·Pattern: ^#[0-9A-Fa-f]{6}$
- primary_gradientGradient | null
  A two-stop linear gradient for the launcher and header.
  3 fieldsGradient
  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 fieldsProactiveTrigger
  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
- send_gradientGradient | null
  A two-stop linear gradient for the launcher and header.
  3 fieldsGradient
  from_colorstringrequired
  Pattern: ^#[0-9A-Fa-f]{6}$
  to_colorstringrequired
  Pattern: ^#[0-9A-Fa-f]{6}$
  angleinteger
  Default: 135·≥ 0 and ≤ 360
- send_shapestring
  One of: circle, rounded, square·Default: rounded
- shadowstring
  One of: none, soft, medium, strong·Default: medium
- show_brandingboolean
  Default: true
- show_citationsboolean
  Default: true
- show_thread_avatarboolean
  Default: true
- show_timestampsboolean
  Default: false
- suggest_followupsboolean
  Default: true
- surface_stylestring
  One of: flat, raised, bordered, glass·Default: raised
- theme_modestring
  One of: auto, light, dark·Default: auto
- theme_versioninteger
  Default: 3·≥ 1 and ≤ 99
- transcript_bgstring | null
  Pattern: ^#[0-9A-Fa-f]{6}$
- typing_indicatorstring
  One of: dots, pulse, wave, shimmer, none·Default: dots
- user_bubble_bgstring | null
  Pattern: ^#[0-9A-Fa-f]{6}$
- user_bubble_stylestring
  One of: soft, flat, outline, glass, tail·Default: soft
- user_bubble_textstring
  Default: #FFFFFF·Pattern: ^#[0-9A-Fa-f]{6}$

Responses#

200OKapplication/json
AgentRead
- 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
- statusAgentStatusrequired
  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
- field_discoveryboolean
  Default: false
- has_api_keyboolean
  Default: false
- language_configobject
- messages_this_monthinteger | null
- thinking_budget_tokensinteger
  Default: 2048
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.

Request · curl

curl -X PATCH "https://api.integrable.cloud/api/agents/$AGENT_ID" \
  -H "Authorization: Bearer $INTEGRABLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_domains": [
      "https://example.com"
    ]
  }'

Set INTEGRABLE_API_KEY and the path variables first. The TypeScript and Python SDKs take the same fields.

Response · 200 OK · 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",
  "field_discovery": false,
  "handoff_enabled": true,
  "has_api_key": false,
  "id": "01a0652b-3713-7ea1-a6c9-2e895389ec34",
  "indexed_chunk_count": 20,
  "is_public": true,
  "language": "string",
  "language_config": {},
  "last_error": "string",
  "lead_capture_config": {},
  "llm_provider": "platform",
  "max_tokens": 0,
  "messages_this_month": 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_budget_tokens": 2048,
  "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: 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-agent limit on top.

More Agents endpoints#

Something unclear or missing? Tell us and we’ll fix it.