Agents API

Create, configure and embed agents: 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.

On this page

Endpoints
Authentication
Objects returned

Endpoints#

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

getList agents/api/agents
postCreate agent/api/agents
postGenerate agent/api/agents/generateBuilds a fully-configured agent from one plain-language description.
getAvailable models/api/agents/modelsModels this org's plan may select, with measured characteristics.
postRehearse blueprint/api/agents/onboarding/rehearseShows what a candidate agent would say, before anything is live.
postScan website/api/agents/onboarding/scanReads a business's website, best pages first.
postGenerate variants/api/agents/onboarding/variantsThree looks of the same agent to choose between (onboarding_service.VARIANTS).
getList widget designs/api/agents/widget/designsThe preset picker's contents, and which of them this plan can use.
getGet agent/api/agents/{agent_id}
patchUpdate agent/api/agents/{agent_id}
deleteDelete agent/api/agents/{agent_id}Soft delete: the agent goes offline immediately and is purged after the retention window, so an accidental deletion is recoverable.
postDuplicate agent/api/agents/{agent_id}/duplicate
getGet embed/api/agents/{agent_id}/embedThe snippet a customer pastes, in two forms.
getGet funnel/api/agents/{agent_id}/funnelImpressions, opens and abandonment - the funnel above the first message.
postRotate key/api/agents/{agent_id}/rotate-keyIssues a new embed key. Every existing embed of this agent stops working.
postSuggest improvements/api/agents/{agent_id}/suggest-improvementsReviews the questions this agent answered badly and proposes fixes.
postTest message/api/agents/{agent_id}/testSends one message through the same retrieval and generation path the widget uses, without creating a conversation.
postUpload avatar/api/agents/{agent_id}/theme/avatarUploads the agent's avatar and points the theme at it.
deleteDelete avatar/api/agents/{agent_id}/theme/avatarRemoves the avatar and clears the theme field.
postGenerate theme/api/agents/{agent_id}/theme/generateA palette from a sentence, or from the customer's own website.
postUpload launcher icon/api/agents/{agent_id}/theme/launcher-iconThe launcher drawn from the tenant's own image - a premium look.
deleteDelete launcher icon/api/agents/{agent_id}/theme/launcher-iconBack to a drawn glyph. Always allowed - removing a premium look never is gated.
postTranslate greeting/api/agents/{agent_id}/translate-greetingThe greeting and suggested questions, translated for the editor.
getList versions/api/agents/{agent_id}/versions
postRestore version/api/agents/{agent_id}/versions/{version}/restore

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_AgentRead_6 fields

itemsarray of AgentReadrequired
38 fieldsAgentRead
- 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
pageintegerrequired
page_sizeintegerrequired
totalintegerrequired
has_moreboolean
Default: false
next_cursorstring | null

AgentRead38 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
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

AgentGenerateResponse4 fields

blueprintAgentBlueprintrequired
The generated configuration, before it becomes an agent.
16 fieldsAgentBlueprint
- 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
- field_discoveryboolean
  Default: false
agentAgentRead | null
38 fieldsAgentRead
- 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
embed_snippetstring | null
import_job_queuedboolean
Default: false

Message2 fields

messagestringrequired
okboolean
Default: true

TestMessageResponse7 fields

contentstringrequired
creditsnumberrequired
input_tokensintegerrequired
latency_msintegerrequired
modelstringrequired
output_tokensintegerrequired
citationsarray of object

AgentVersionRead4 fields

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

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