DocsAPI reference

Generate agent

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

post/api/agents/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 agent 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

AgentGenerateRequest

  • descriptionstringrequired

    What the business does, who it serves, and what the agent 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.

Responses#

  • 200OKapplication/json

    AgentGenerateResponse

    • 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

    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.

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.