Chatbots

Operations tagged Chatbots in the public API.

About Chatbots

A chatbot (an agent in the dashboard) is the unit everything else hangs off: knowledge is trained into one, conversations happen with one, and its widget, hosted agent page and messaging channels each serve one.

Lifecycle. POST /chatbots creates it as draft. The website widget and the hosted agent page serve only an active chatbot: POST /chatbots/{id}/activate puts it live there, POST /chatbots/{id}/deactivate takes it offline (POST /chat answers for a chatbot in any status). Training is separate: training_status follows its knowledge, and GET /chatbots/{id}/readiness reports ready once the chatbot is active and training is completed. DELETE /chatbots/{id} removes it with its knowledge, conversations, channels and plugin installations.

IDs you will meet.

id — an integer, in every /chatbots/{id} path and as chatbot_id everywhere else (POST /chat, GET /conversations, POST /knowledge, …).
slug — the chatbot's public handle, the address of its hosted agent page (/agent/{handle}), unique across the platform. GET /chatbots/by_handle/{handle} resolves it; PUT /chatbots/{id}/handle changes it.
Access account id — an integer naming one visitor login of a credentialed hosted page (GET /chatbots/{id}/access → accounts[].id).

IDs on this page

Chatbot handle<HANDLE>: String: lowercase letters and digits with single inner hyphens, 3–40 characters, never all digits.
Get it from
GET /v1/chatbots returns it as data[].slug
GET /v1/chatbots/{id} returns it as slug
GET /v1/chatbots/{id}/access returns it as handle
It is the last segment of the chatbot's hosted page address, /agent/{handle}.
Chatbot id<CHATBOT_ID>: Integer.
Get it from
GET /v1/chatbots returns it as data[].id
POST /v1/chatbots returns it as id
GET /v1/chatbots/by_handle/{handle} returns it as id
Webhook chatbot.created carries it as data.object.id
In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.
Access account id<ACCOUNT_ID>: Integer.
Get it from
POST /v1/chatbots/{id}/access/accounts returns it as id
GET /v1/chatbots/{id}/access returns it as accounts[].id

/v1/chatbots

List chatbots

Returns the account's chatbots, newest first and cursor-paginated. Narrow the list by status, training_status or a search on the name; the filters combine. An unknown status or training_status is 422 VALIDATION_FAILED, never an empty page.

Required scope: chatbots:read
Idempotency: Read-only
Rate limits

Query parameters

statusstringnullableOptional
Only chatbots in this lifecycle status: active, inactive or draft.
Possible valuesactiveinactivedraftnull
training_statusstringnullableOptional
Only chatbots whose knowledge training is in this state.
Possible valuesnever_trainedpendingtrainingupdatingneeds_retrainingcompletedfailednull
searchstringnullableOptional
Substring match on the chatbot name (two characters or more; Arabic spelling variants such as ه/ة, ي/ى and ا/أ/إ/آ match each other).
Max length: 100
limitintegerOptional
Page size, clamped to 1–100.
Default: 20Minimum: 1Maximum: 100
starting_afterstringOptional
Cursor from a previous page's next_cursor: returns the page after it. A cursor minted for another list, sort or order is 422 INVALID_CURSOR.
ending_beforestringOptional
Cursor from a previous page's previous_cursor: returns the page before it. Wins when both cursors are sent.
created[gte]stringOptional
Only rows created on or after this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.
created[lte]stringOptional
Only rows created on or before this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.

Responses

200
Success.
objectstringRequired
Alwayslist
dataarray of ChatbotResourceRequired
has_morebooleanRequired
next_cursorstringnullableRequired
previous_cursorstringnullableRequired
urlstringRequired
Always/v1/chatbots
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
422
Validation failed. See error.details.
Error codesINVALID_CURSOR INVALID_PARAMETER VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/chatbots' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "list",
  "data": [
    {
      "object": "chatbot",
      "id": 1,
      "slug": "orders-assistant",
      "name": "Orders Assistant",
      "description": "Tracks orders and deliveries.",
      "avatar_url": null,
      "color": "bg-indigo-500",
      "primary_language": "English",
      "supported_languages": [],
      "text_direction": "LTR",
      "status": "active",
      "training_status": "never_trained",
      "cache_responses": true,
      "last_training_date": null,
      "last_active_at": null,
      "template_id": null,
      "response_length": "Short Response",
      "audience": "customers",
      "knowledge_mode": "strict",
      "welcome_message": null,
      "fallback_message": null,
      "custom_instructions": [],
      "enable_handoff": false,
      "training_config": [],
      "gradient_style": "from-indigo-600 to-blue-600",
      "header_theme": "gradient",
      "is_image_avatar": false,
      "settings": [],
      "lead_capture": null,
      "allowed_domains": [],
      "created_at": "2026-01-01T00:00:00+00:00",
      "updated_at": "2026-01-01T00:00:00+00:00"
    },
    {
      "object": "chatbot",
      "id": 1,
      "slug": "support-assistant",
      "name": "Support Assistant",
      "description": "Answers billing and shipping questions.",
      "avatar_url": null,
      "color": "bg-indigo-500",
      "primary_language": "English",
      "supported_languages": [],
      "text_direction": "LTR",
      "status": "active",
      "training_status": "never_trained",
      "cache_responses": true,
      "last_training_date": null,
      "last_active_at": null,
      "template_id": null,
      "response_length": "Short Response",
      "audience": "customers",
      "knowledge_mode": "strict",
      "welcome_message": null,
      "fallback_message": null,
      "custom_instructions": [],
      "enable_handoff": false,
      "training_config": [],
      "gradient_style": "from-indigo-600 to-blue-600",
      "header_theme": "gradient",
      "is_image_avatar": false,
      "settings": [],
      "lead_capture": null,
      "allowed_domains": [
        "shop.example.com"
      ],
      "created_at": "2026-01-01T00:00:00+00:00",
      "updated_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/chatbots"
}

/v1/chatbots

Create a chatbot

Creates a chatbot and returns it with 201. Only name is required; every other field takes the platform default (English, short answers, the default theme, customers audience answering in strict knowledge mode). The chatbot starts draft and never_trained: add knowledge with POST /knowledge, then POST /chatbots/{id}/activate to serve it on the widget and hosted page. The name is unique within the account: a taken name is 409 CHATBOT_NAME_TAKEN. The plan's agent cap is checked after the name: at the cap it is 402 AGENT_LIMIT_REACHED. A retry with the same Idempotency-Key returns the chatbot the first request created.

Required scope: chatbots:write
Idempotency: Accepts Idempotency-Key
Webhook events: chatbot.created
Rate limits

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

Public /v1 create chatbot payload. The field set is PINNED here (plan H4): {@see FIELDS} is the exhaustive list of top-level keys the public contract accepts, and {@see rules()} keeps only the dashboard rules for those keys. A rule added to the dashboard request for a new dashboard-only field therefore never reaches /v1 (and never appears in the generated OpenAPI document) until it is deliberately added to this list. The per-field rules themselves are shared so the two surfaces cannot disagree on a field they both accept. Deliberately absent: the body idempotency_key — /v1 clients send the Idempotency-Key header (docs/03-domains/public-api). audience / knowledge_mode are REQUIRED on the dashboard (the intent steps) but sometimes here ({@see OPTIONAL_ON_V1}): an API client that never heard of them keeps creating business agents answering from their knowledge only (customers + strict, the pre-existing behaviour).

template_idintegernullableOptional
The catalogue template to start from (an active template id); null for none. /v1 has no operation that lists templates.
namestringRequired
Display name, at most 255 characters. Unique within the account: a taken name is 409 CHATBOT_NAME_TAKEN.
Max length: 255
descriptionstringnullableOptional
Optional longer description.
Max length: 500
audiencestringOptional
Who the agent serves: customers (it speaks for the business) or personal (the owner's private assistant). Defaults to customers when omitted.
Possible valuescustomerspersonal
knowledge_modestringOptional
How far answers may step outside the knowledge base: strict (knowledge only) or general (general knowledge when the knowledge base is silent, flagged as such). Defaults to strict when omitted.
Possible valuesstrictgeneral
primary_languagestringOptional
Content language. Defaults to English when omitted.
Possible valuesEnglishArabicSpanishFrenchGermanPortugueseHindiBengaliUrduJapaneseIndonesianTurkishRussianKoreanVietnamese
text_directionstringOptional
Derived from primary_language; a client-supplied value is accepted and ignored.
Possible valuesLTRRTL
response_lengthstringOptional
Answer length preset. Defaults to Short Response when omitted.
Possible valuesShort ResponseLong Response
cache_responsesbooleannullableOptional
Whether a repeated question may be answered from the response cache instead of a new model call. Defaults to true.
welcome_messagestringnullableOptional
The first message the widget and hosted page show, at most 2000 characters; null for the default greeting.
Max length: 2000
fallback_messagestringnullableOptional
The reply sent when the chatbot cannot produce an answer, at most 2000 characters; null for the platform default.
Max length: 2000
custom_instructionsarray of stringnullableOptional
Extra instructions applied to every answer, one non-empty string (at most 500 characters) per instruction. The plan caps how many.
Max items: 1
gradient_styleany ofOptional
Header gradient: a theme catalog token or a custom two-stop #rrggbb,#rrggbb pair. Hex input is normalised (#RGB, upper case and a missing # are accepted); alpha hex (#rrggbbaa) is refused. A pair on which no text colour (#ffffff, #1f2937, #000000) reaches 4.5:1 at both ends is refused with 422 VALIDATION_FAILED on gradient_style. Defaults to the wizard default when omitted.
Max length: 100
header_themestringnullableOptional
Header fill mode: gradient (uses gradient_style) or flat (uses color). Defaults to gradient.
Possible valuesflatgradientnull
colorany ofnullableOptional
Flat header colour: a theme catalog token or a custom #rrggbb. Hex input is normalised (#RGB, upper case and a missing # are accepted); alpha hex (#rrggbbaa) is refused. Any colour is accepted: the text colour is picked automatically (#ffffff, #1f2937 or #000000) to reach WCAG AA 4.5:1. Defaults to the wizard default when omitted.
Max length: 20
avatarstringnullableOptional
A stored avatar reference: the path of an image this account uploaded (/uploads/avatars/…), a bundled default avatar or a hex colour; null clears it. To upload a new image use POST /chatbots/{id}/avatar.
Max length: 500
is_image_avatarbooleanOptional
Whether avatar is an uploaded image rather than a colour or default avatar.
enable_handoffbooleanOptional
Whether the chatbot may hand a conversation to a human. The first handoff of a conversation emits conversation.handoff.requested. Defaults to false.
settingsobjectOptional
Widget / behaviour settings bag. Only the documented keys are accepted; unknown keys are a 422.
lead_captureobjectOptional
Optional pre-reply lead capture configuration. Only the documented keys are accepted.

Responses

201
ChatbotResource
objectstringRequired
Alwayschatbot
idintegerRequired
The chatbot id, used in every /chatbots/{id} path and as chatbot_id elsewhere.
slugstringRequired
The public handle: the hosted agent page lives at /agent/{slug}. Unique across the platform; PUT /chatbots/{id}/handle changes it, a rename never does.
namestringRequired
Display name, unique within the account.
descriptionstringnullableRequired
Your own description of the chatbot; null when none.
avatar_urlstringnullableRequired
Absolute URL of the avatar image; null when the chatbot has none.
colorstringRequired
Flat header colour: a theme token or a #rrggbb hex. Used when header_theme is flat.
primary_languagestringRequired
The language the chatbot answers in, e.g. English.
supported_languagesobjectRequired
Further languages the chatbot is set up for; [] when none.
text_directionstringRequired
LTR or RTL, derived from primary_language.
statusstringRequired
Lifecycle status. The widget and hosted page serve only an active chatbot; a new one is draft.
Possible valuesactiveinactivedraft
training_statusstringRequired
Where training of the chatbot's knowledge stands. completed once every source is trained; never_trained before any.
Possible valuesnever_trainedpendingtrainingupdatingneeds_retrainingcompletedfailed
cache_responsesbooleanRequired
Whether a repeated question may be answered from the response cache instead of a new model call.
last_training_datestringnullableRequired
When training last completed (ISO 8601, UTC); null before the first.
last_active_atstringnullableRequired
When the chatbot last answered a chat turn (ISO 8601, UTC); null before the first.
template_idintegernullableRequired
The catalogue template the chatbot was created from; null when none.
response_lengthstringRequired
Answer length preset: Short Response or Long Response.
audiencestringRequired
Who the chatbot serves: customers (it speaks for the business) or personal (the owner's private assistant). customers unless set at creation.
knowledge_modestringRequired
How far answers may step outside the knowledge base: strict (knowledge only) or general (general knowledge when the knowledge base has nothing). strict unless set at creation.
welcome_messagestringnullableRequired
The first message the widget and hosted page show; null for the default greeting.
fallback_messagestringnullableRequired
The reply sent when the chatbot cannot produce an answer; null for the platform default.
custom_instructionsobjectRequired
Your extra instructions for every answer, one string per instruction; [] when none. The plan caps how many.
enable_handoffbooleanRequired
Whether the chatbot may hand a conversation to a human.
training_configobjectRequired
Training and retrieval tuning set through PATCH /chatbots/{id}; [] when never set.
gradient_stylestringRequired
Header gradient: a theme token or a #rrggbb,#rrggbb pair. Used when header_theme is gradient.
header_themestringRequired
Header fill: gradient (uses gradient_style) or flat (uses color).
is_image_avatarbooleanRequired
Whether the avatar is an uploaded image (POST /chatbots/{id}/avatar).
settingsobjectRequired
The widget look-and-behaviour keys set on the chatbot (PUT /chatbots/{chatbotId}/widget). A key never set is absent.
lead_captureobjectnullableRequired
Lead capture: whether the widget asks visitors for contact details (enabled), when (trigger), which fields, and whether they may skip it; null when never configured.
allowed_domainsobjectRequired
Hostnames whose pages may load the widget; [] lets it load on any site. Managed with the /chatbots/{chatbotId}/widget/domains operations.
created_atstringnullableRequired
When the chatbot was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the chatbot last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
402
A billing gate refused the request (plan limit, monthly AI budget or message credits). See error.code.
Error codesAGENT_LIMIT_REACHED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
409
The request conflicts with the current resource state.
Error codesCHATBOT_NAME_TAKEN IDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/chatbots' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "template_id": 1,
  "name": "name",
  "description": "description",
  "audience": "audience",
  "knowledge_mode": "knowledge_mode",
  "primary_language": "primary_language",
  "text_direction": "text_direction",
  "response_length": "response_length"
}'

Response

Example 201 response

json

{
  "object": "chatbot",
  "id": 1,
  "slug": "returns-assistant",
  "name": "Returns Assistant",
  "description": "Handles returns and exchanges.",
  "avatar_url": null,
  "color": "bg-indigo-600",
  "primary_language": "English",
  "supported_languages": [
    "English"
  ],
  "text_direction": "LTR",
  "status": "draft",
  "training_status": "never_trained",
  "cache_responses": true,
  "last_training_date": null,
  "last_active_at": null,
  "template_id": null,
  "response_length": "Short Response",
  "audience": "customers",
  "knowledge_mode": "strict",
  "welcome_message": null,
  "fallback_message": null,
  "custom_instructions": [],
  "enable_handoff": false,
  "training_config": [],
  "gradient_style": "from-primary-800 to-primary-600",
  "header_theme": "gradient",
  "is_image_avatar": false,
  "settings": [],
  "lead_capture": null,
  "allowed_domains": [],
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/chatbots/by_handle/{handle}

Retrieve a chatbot by handle

Looks a chatbot up by its public handle (slug, the last segment of its hosted page address /agent/{handle}) when you have the handle but not the integer id. A handle that belongs to another account, or to no chatbot, is 404 NOT_FOUND.

Required scope: chatbots:read
Idempotency: Read-only
Rate limits

Before you call

handle(path)Chatbot handle
String: lowercase letters and digits with single inner hyphens, 3–40 characters, never all digits.
Placeholder in the samples: <HANDLE>
Get it from
- GET /v1/chatbots returns it as data[].slug
- GET /v1/chatbots/{id} returns it as slug
- GET /v1/chatbots/{id}/access returns it as handle
- It is the last segment of the chatbot's hosted page address, /agent/{handle}.

Path parameters

handlestringRequired
The chatbot's handle (slug).

Responses

200
ChatbotResource
objectstringRequired
Alwayschatbot
idintegerRequired
The chatbot id, used in every /chatbots/{id} path and as chatbot_id elsewhere.
slugstringRequired
The public handle: the hosted agent page lives at /agent/{slug}. Unique across the platform; PUT /chatbots/{id}/handle changes it, a rename never does.
namestringRequired
Display name, unique within the account.
descriptionstringnullableRequired
Your own description of the chatbot; null when none.
avatar_urlstringnullableRequired
Absolute URL of the avatar image; null when the chatbot has none.
colorstringRequired
Flat header colour: a theme token or a #rrggbb hex. Used when header_theme is flat.
primary_languagestringRequired
The language the chatbot answers in, e.g. English.
supported_languagesobjectRequired
Further languages the chatbot is set up for; [] when none.
text_directionstringRequired
LTR or RTL, derived from primary_language.
statusstringRequired
Lifecycle status. The widget and hosted page serve only an active chatbot; a new one is draft.
Possible valuesactiveinactivedraft
training_statusstringRequired
Where training of the chatbot's knowledge stands. completed once every source is trained; never_trained before any.
Possible valuesnever_trainedpendingtrainingupdatingneeds_retrainingcompletedfailed
cache_responsesbooleanRequired
Whether a repeated question may be answered from the response cache instead of a new model call.
last_training_datestringnullableRequired
When training last completed (ISO 8601, UTC); null before the first.
last_active_atstringnullableRequired
When the chatbot last answered a chat turn (ISO 8601, UTC); null before the first.
template_idintegernullableRequired
The catalogue template the chatbot was created from; null when none.
response_lengthstringRequired
Answer length preset: Short Response or Long Response.
audiencestringRequired
Who the chatbot serves: customers (it speaks for the business) or personal (the owner's private assistant). customers unless set at creation.
knowledge_modestringRequired
How far answers may step outside the knowledge base: strict (knowledge only) or general (general knowledge when the knowledge base has nothing). strict unless set at creation.
welcome_messagestringnullableRequired
The first message the widget and hosted page show; null for the default greeting.
fallback_messagestringnullableRequired
The reply sent when the chatbot cannot produce an answer; null for the platform default.
custom_instructionsobjectRequired
Your extra instructions for every answer, one string per instruction; [] when none. The plan caps how many.
enable_handoffbooleanRequired
Whether the chatbot may hand a conversation to a human.
training_configobjectRequired
Training and retrieval tuning set through PATCH /chatbots/{id}; [] when never set.
gradient_stylestringRequired
Header gradient: a theme token or a #rrggbb,#rrggbb pair. Used when header_theme is gradient.
header_themestringRequired
Header fill: gradient (uses gradient_style) or flat (uses color).
is_image_avatarbooleanRequired
Whether the avatar is an uploaded image (POST /chatbots/{id}/avatar).
settingsobjectRequired
The widget look-and-behaviour keys set on the chatbot (PUT /chatbots/{chatbotId}/widget). A key never set is absent.
lead_captureobjectnullableRequired
Lead capture: whether the widget asks visitors for contact details (enabled), when (trigger), which fields, and whether they may skip it; null when never configured.
allowed_domainsobjectRequired
Hostnames whose pages may load the widget; [] lets it load on any site. Managed with the /chatbots/{chatbotId}/widget/domains operations.
created_atstringnullableRequired
When the chatbot was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the chatbot last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/chatbots/by_handle/<HANDLE>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "chatbot",
  "id": 1,
  "slug": "support-assistant",
  "name": "Support Assistant",
  "description": "Answers billing and shipping questions.",
  "avatar_url": null,
  "color": "bg-indigo-500",
  "primary_language": "English",
  "supported_languages": [],
  "text_direction": "LTR",
  "status": "active",
  "training_status": "never_trained",
  "cache_responses": true,
  "last_training_date": null,
  "last_active_at": null,
  "template_id": null,
  "response_length": "Short Response",
  "audience": "customers",
  "knowledge_mode": "strict",
  "welcome_message": null,
  "fallback_message": null,
  "custom_instructions": [],
  "enable_handoff": false,
  "training_config": [],
  "gradient_style": "from-indigo-600 to-blue-600",
  "header_theme": "gradient",
  "is_image_avatar": false,
  "settings": [],
  "lead_capture": null,
  "allowed_domains": [
    "shop.example.com"
  ],
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/chatbots/{id}

Retrieve a chatbot

Returns one chatbot with everything its settings page shows: identity (name, slug), answer behaviour (audience, knowledge_mode, response_length, messages and instructions), appearance, widget settings, lead_capture and the widget allowlist. A chatbot of another account is 404 NOT_FOUND.

Required scope: chatbots:read
Idempotency: Read-only
Rate limits

Before you call

id(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

idintegerRequired
The chatbot id.

Responses

200
ChatbotResource
objectstringRequired
Alwayschatbot
idintegerRequired
The chatbot id, used in every /chatbots/{id} path and as chatbot_id elsewhere.
slugstringRequired
The public handle: the hosted agent page lives at /agent/{slug}. Unique across the platform; PUT /chatbots/{id}/handle changes it, a rename never does.
namestringRequired
Display name, unique within the account.
descriptionstringnullableRequired
Your own description of the chatbot; null when none.
avatar_urlstringnullableRequired
Absolute URL of the avatar image; null when the chatbot has none.
colorstringRequired
Flat header colour: a theme token or a #rrggbb hex. Used when header_theme is flat.
primary_languagestringRequired
The language the chatbot answers in, e.g. English.
supported_languagesobjectRequired
Further languages the chatbot is set up for; [] when none.
text_directionstringRequired
LTR or RTL, derived from primary_language.
statusstringRequired
Lifecycle status. The widget and hosted page serve only an active chatbot; a new one is draft.
Possible valuesactiveinactivedraft
training_statusstringRequired
Where training of the chatbot's knowledge stands. completed once every source is trained; never_trained before any.
Possible valuesnever_trainedpendingtrainingupdatingneeds_retrainingcompletedfailed
cache_responsesbooleanRequired
Whether a repeated question may be answered from the response cache instead of a new model call.
last_training_datestringnullableRequired
When training last completed (ISO 8601, UTC); null before the first.
last_active_atstringnullableRequired
When the chatbot last answered a chat turn (ISO 8601, UTC); null before the first.
template_idintegernullableRequired
The catalogue template the chatbot was created from; null when none.
response_lengthstringRequired
Answer length preset: Short Response or Long Response.
audiencestringRequired
Who the chatbot serves: customers (it speaks for the business) or personal (the owner's private assistant). customers unless set at creation.
knowledge_modestringRequired
How far answers may step outside the knowledge base: strict (knowledge only) or general (general knowledge when the knowledge base has nothing). strict unless set at creation.
welcome_messagestringnullableRequired
The first message the widget and hosted page show; null for the default greeting.
fallback_messagestringnullableRequired
The reply sent when the chatbot cannot produce an answer; null for the platform default.
custom_instructionsobjectRequired
Your extra instructions for every answer, one string per instruction; [] when none. The plan caps how many.
enable_handoffbooleanRequired
Whether the chatbot may hand a conversation to a human.
training_configobjectRequired
Training and retrieval tuning set through PATCH /chatbots/{id}; [] when never set.
gradient_stylestringRequired
Header gradient: a theme token or a #rrggbb,#rrggbb pair. Used when header_theme is gradient.
header_themestringRequired
Header fill: gradient (uses gradient_style) or flat (uses color).
is_image_avatarbooleanRequired
Whether the avatar is an uploaded image (POST /chatbots/{id}/avatar).
settingsobjectRequired
The widget look-and-behaviour keys set on the chatbot (PUT /chatbots/{chatbotId}/widget). A key never set is absent.
lead_captureobjectnullableRequired
Lead capture: whether the widget asks visitors for contact details (enabled), when (trigger), which fields, and whether they may skip it; null when never configured.
allowed_domainsobjectRequired
Hostnames whose pages may load the widget; [] lets it load on any site. Managed with the /chatbots/{chatbotId}/widget/domains operations.
created_atstringnullableRequired
When the chatbot was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the chatbot last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "chatbot",
  "id": 1,
  "slug": "support-assistant",
  "name": "Support Assistant",
  "description": "Answers billing and shipping questions.",
  "avatar_url": null,
  "color": "bg-indigo-500",
  "primary_language": "English",
  "supported_languages": [],
  "text_direction": "LTR",
  "status": "active",
  "training_status": "never_trained",
  "cache_responses": true,
  "last_training_date": null,
  "last_active_at": null,
  "template_id": null,
  "response_length": "Short Response",
  "audience": "customers",
  "knowledge_mode": "strict",
  "welcome_message": null,
  "fallback_message": null,
  "custom_instructions": [],
  "enable_handoff": false,
  "training_config": [],
  "gradient_style": "from-indigo-600 to-blue-600",
  "header_theme": "gradient",
  "is_image_avatar": false,
  "settings": [],
  "lead_capture": null,
  "allowed_domains": [
    "shop.example.com"
  ],
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/chatbots/{id}

Update a chatbot

Changes only the fields you send. settings is merged key by key into the stored settings (keys you omit keep their value); every other field replaces its value. Renaming to a name another chatbot of the account already has is 409 CHATBOT_NAME_TAKEN; a rename never changes the handle (slug), so shared links keep working. status can be set here too, but only POST /chatbots/{id}/activate and /deactivate emit chatbot.activated / chatbot.deactivated; this operation emits chatbot.updated.

Required scope: chatbots:write
Idempotency: Accepts Idempotency-Key
Webhook events: chatbot.updated
Rate limits

Before you call

id(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

idintegerRequired
The chatbot id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

Public /v1 update chatbot payload. Field set is pinned on this class so a dashboard FormRequest tweak cannot silently widen the public contract.

namestringOptional
Display name, at most 255 characters. Renaming to a name another chatbot of the account has is 409 CHATBOT_NAME_TAKEN. The handle (slug) does not change.
Max length: 255
descriptionstringnullableOptional
Optional longer description.
Max length: 500
primary_languagestringOptional
The language the chatbot answers in. Omit it to keep the current one; text_direction follows it.
Possible valuesEnglishArabicSpanishFrenchGermanPortugueseHindiBengaliUrduJapaneseIndonesianTurkishRussianKoreanVietnamese
supported_languagesarray of stringOptional
Further languages the chatbot is set up for, from the same list as primary_language. Replaces the stored list.
text_directionstringOptional
Derived from primary_language; a client-supplied value is accepted and ignored.
Possible valuesLTRRTL
response_lengthstringOptional
Answer length preset: Short Response or Long Response.
Possible valuesShort ResponseLong Response
audiencestringOptional
Who the agent serves: customers (it speaks for the business) or personal (the owner's private assistant).
Possible valuescustomerspersonal
knowledge_modestringOptional
How far answers may step outside the knowledge base: strict (knowledge only) or general (general knowledge when the knowledge base is silent, flagged as such).
Possible valuesstrictgeneral
welcome_messagestringnullableOptional
The first message the widget and hosted page show, at most 2000 characters; null for the default greeting.
Max length: 2000
fallback_messagestringnullableOptional
The reply sent when the chatbot cannot produce an answer, at most 2000 characters; null for the platform default.
Max length: 2000
custom_instructionsarray of stringOptional
Extra instructions applied to every answer, one non-empty string (at most 500 characters) per instruction. The plan caps how many. Replaces the stored list.
Max items: 1
enable_handoffbooleanOptional
Whether the chatbot may hand a conversation to a human. The first handoff of a conversation emits conversation.handoff.requested.
cache_responsesbooleanOptional
Whether a repeated question may be answered from the response cache instead of a new model call.
gradient_styleany ofOptional
Header gradient: a theme catalog token or a custom two-stop #rrggbb,#rrggbb pair. Hex input is normalised (#RGB, upper case and a missing # are accepted); alpha hex (#rrggbbaa) is refused. A pair on which no text colour (#ffffff, #1f2937, #000000) reaches 4.5:1 at both ends is refused with 422 VALIDATION_FAILED on gradient_style. Defaults to the wizard default when omitted.
Max length: 100
header_themestringOptional
Header fill: gradient (uses gradient_style) or flat (uses color).
Possible valuesflatgradient
avatarstringnullableOptional
A stored avatar reference: the path of an image this account uploaded (/uploads/avatars/…), a bundled default avatar or a hex colour; null clears it. To upload a new image use POST /chatbots/{id}/avatar.
Max length: 512
colorany ofOptional
Flat header colour: a theme catalog token or a custom #rrggbb. Hex input is normalised (#RGB, upper case and a missing # are accepted); alpha hex (#rrggbbaa) is refused. Any colour is accepted: the text colour is picked automatically (#ffffff, #1f2937 or #000000) to reach WCAG AA 4.5:1. Defaults to the wizard default when omitted.
Max length: 20
is_image_avatarbooleanOptional
Whether avatar is an uploaded image rather than a colour or default avatar.
settingsobjectOptional
Widget / behaviour settings bag. Only the documented keys are accepted; unknown keys are a 422.
training_configarray of stringOptional
Training and retrieval tuning. Replaces the stored value; read it back as training_config.
allowed_domainsarray of stringOptional
The complete widget allowlist, with the same hostname rules and cap as PUT /chatbots/{chatbotId}/widget/domains. Prefer the widget domain operations: they change one host at a time and never drop a host an active plugin installation owns.
Max items: 50
statusstringOptional
Lifecycle status: draft, active or inactive. Setting it here emits only chatbot.updated; POST /chatbots/{id}/activate and /deactivate also emit chatbot.activated / chatbot.deactivated.
Possible valuesdraftactiveinactive
template_idintegerOptional
The catalogue template the chatbot is based on (an active template id). /v1 has no operation that lists templates.
lead_captureobjectOptional
Optional pre-reply lead capture configuration. Only the documented keys are accepted.

Responses

200
ChatbotResource
objectstringRequired
Alwayschatbot
idintegerRequired
The chatbot id, used in every /chatbots/{id} path and as chatbot_id elsewhere.
slugstringRequired
The public handle: the hosted agent page lives at /agent/{slug}. Unique across the platform; PUT /chatbots/{id}/handle changes it, a rename never does.
namestringRequired
Display name, unique within the account.
descriptionstringnullableRequired
Your own description of the chatbot; null when none.
avatar_urlstringnullableRequired
Absolute URL of the avatar image; null when the chatbot has none.
colorstringRequired
Flat header colour: a theme token or a #rrggbb hex. Used when header_theme is flat.
primary_languagestringRequired
The language the chatbot answers in, e.g. English.
supported_languagesobjectRequired
Further languages the chatbot is set up for; [] when none.
text_directionstringRequired
LTR or RTL, derived from primary_language.
statusstringRequired
Lifecycle status. The widget and hosted page serve only an active chatbot; a new one is draft.
Possible valuesactiveinactivedraft
training_statusstringRequired
Where training of the chatbot's knowledge stands. completed once every source is trained; never_trained before any.
Possible valuesnever_trainedpendingtrainingupdatingneeds_retrainingcompletedfailed
cache_responsesbooleanRequired
Whether a repeated question may be answered from the response cache instead of a new model call.
last_training_datestringnullableRequired
When training last completed (ISO 8601, UTC); null before the first.
last_active_atstringnullableRequired
When the chatbot last answered a chat turn (ISO 8601, UTC); null before the first.
template_idintegernullableRequired
The catalogue template the chatbot was created from; null when none.
response_lengthstringRequired
Answer length preset: Short Response or Long Response.
audiencestringRequired
Who the chatbot serves: customers (it speaks for the business) or personal (the owner's private assistant). customers unless set at creation.
knowledge_modestringRequired
How far answers may step outside the knowledge base: strict (knowledge only) or general (general knowledge when the knowledge base has nothing). strict unless set at creation.
welcome_messagestringnullableRequired
The first message the widget and hosted page show; null for the default greeting.
fallback_messagestringnullableRequired
The reply sent when the chatbot cannot produce an answer; null for the platform default.
custom_instructionsobjectRequired
Your extra instructions for every answer, one string per instruction; [] when none. The plan caps how many.
enable_handoffbooleanRequired
Whether the chatbot may hand a conversation to a human.
training_configobjectRequired
Training and retrieval tuning set through PATCH /chatbots/{id}; [] when never set.
gradient_stylestringRequired
Header gradient: a theme token or a #rrggbb,#rrggbb pair. Used when header_theme is gradient.
header_themestringRequired
Header fill: gradient (uses gradient_style) or flat (uses color).
is_image_avatarbooleanRequired
Whether the avatar is an uploaded image (POST /chatbots/{id}/avatar).
settingsobjectRequired
The widget look-and-behaviour keys set on the chatbot (PUT /chatbots/{chatbotId}/widget). A key never set is absent.
lead_captureobjectnullableRequired
Lead capture: whether the widget asks visitors for contact details (enabled), when (trigger), which fields, and whether they may skip it; null when never configured.
allowed_domainsobjectRequired
Hostnames whose pages may load the widget; [] lets it load on any site. Managed with the /chatbots/{chatbotId}/widget/domains operations.
created_atstringnullableRequired
When the chatbot was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the chatbot last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesCHATBOT_NAME_TAKEN IDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X PATCH 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "name": "name",
  "description": "description",
  "primary_language": "primary_language",
  "supported_languages": [],
  "text_direction": "text_direction",
  "response_length": "response_length",
  "audience": "audience",
  "knowledge_mode": "knowledge_mode"
}'

Response

Example 200 response

json

{
  "object": "chatbot",
  "id": 1,
  "slug": "orders-assistant",
  "name": "Orders Assistant",
  "description": "Tracks orders and deliveries.",
  "avatar_url": null,
  "color": "bg-indigo-500",
  "primary_language": "English",
  "supported_languages": [],
  "text_direction": "LTR",
  "status": "active",
  "training_status": "never_trained",
  "cache_responses": true,
  "last_training_date": null,
  "last_active_at": null,
  "template_id": null,
  "response_length": "Short Response",
  "audience": "customers",
  "knowledge_mode": "strict",
  "welcome_message": "Hi! Ask me about orders, shipping or refunds.",
  "fallback_message": null,
  "custom_instructions": [],
  "enable_handoff": false,
  "training_config": [],
  "gradient_style": "from-indigo-600 to-blue-600",
  "header_theme": "gradient",
  "is_image_avatar": false,
  "settings": {
    "widget_position": "bottom-left"
  },
  "lead_capture": null,
  "allowed_domains": [],
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/chatbots/{id}

Delete a chatbot

Permanently deletes the chatbot with everything that belongs to it: its knowledge (and the vectors behind it), crawls, conversations and their messages, channels, plugin installations and avatar. There is no undo. In-flight crawls are cancelled first. The messaging platforms are not told: disconnect the chatbot's channels first (DELETE /chatbots/{chatbotId}/channels/{platform}) if their webhooks should be removed. A key limited to chosen chatbots needs admin access on this one.

Required scope: chatbots:write
Idempotency: Accepts Idempotency-Key
Webhook events: chatbot.deleted
Rate limits

Before you call

id(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

idintegerRequired
The chatbot id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Responses

200
Success.
objectstringRequired
Alwayschatbot
idintegerRequired
deletedbooleanRequired
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X DELETE 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "chatbot",
  "id": 1,
  "deleted": true
}

/v1/chatbots/{id}/readiness

Check whether a chatbot is ready

Reports whether the chatbot is live and trained: ready is true only when status is active and training_status is completed. Poll it after creating a chatbot and adding knowledge, or subscribe to knowledge.dataset.trained instead. ready: false does not block POST /chat, which answers for a chatbot in any status: it means the widget and hosted page do not serve the chatbot yet, or its knowledge is not fully trained (any training_status other than completed).

Required scope: chatbots:read
Idempotency: Read-only
Rate limits

Before you call

id(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

idintegerRequired
The chatbot id.

Responses

200
Success.
objectstringRequired
Alwayschatbot_readiness
idintegerRequired
The chatbot id.
statusstringRequired
The chatbot's lifecycle status: active, inactive or draft.
training_statusstringRequired
Where training of the chatbot's knowledge stands.
documents_countintegerRequired
Knowledge documents the chatbot holds.
knowledge_size_bytesintegerRequired
Size of the chatbot's knowledge, the measure the plan's knowledge quota counts: extracted text characters, one byte each.
readybooleanRequired
true when status is active and training_status is completed.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/readiness' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "chatbot_readiness",
  "id": 1,
  "status": "active",
  "training_status": "never_trained",
  "documents_count": 0,
  "knowledge_size_bytes": 500,
  "ready": false
}

/v1/chatbots/{id}/access

Retrieve a chatbot's hosted page access

Returns who may open the chatbot's hosted agent page (/agent/{handle}): whether the page is published (hosted_page_enabled), the access mode and whether its gate is on, whether a share secret or password is set (never their values), and the visitor logins of credentialed mode.

Required scope: chatbots:read
Idempotency: Read-only
Rate limits

Before you call

id(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

idintegerRequired
The chatbot id.

Responses

200
AgentAccessResource
chatbot_idintegerRequired
The chatbot this access configuration belongs to.
handlestringRequired
The chatbot's public handle: its hosted page lives at /agent/{handle}.
hosted_page_enabledbooleanRequired
Whether the hosted agent page is published at all. While false the page is offline whatever mode says.
modestringRequired
Who may open the hosted page: public (anyone with the link), secret (the link plus the share secret), password (a shared password) or credentialed (one of the visitor logins in accounts).
Possible valuespublicsecretpasswordcredentialed
enabledbooleanRequired
Whether the gate of mode is on. Always false in public mode; a disabled gate behaves like public.
has_secretbooleanRequired
Whether a share secret is stored. The secret itself is returned once, by the PUT /chatbots/{id}/access that minted it.
has_passwordbooleanRequired
Whether a shared password is stored for password mode. The password is never returned.
token_versionintegerRequired
Revocation epoch of the visitor access tokens. PUT /chatbots/{id}/access with revoke: true raises it, which signs every visitor out.
max_accountsintegerRequired
How many visitor logins accounts may hold.
accountsarray of AgentAccessAccountResourceOptional
The visitor logins of credentialed mode, managed with POST and DELETE /chatbots/{id}/access/accounts.
objectstringRequired
Alwayschatbot_access
idintegerRequired
The chatbot id (the same value as chatbot_id).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/access' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "chatbot_id": 1,
  "handle": "support-assistant",
  "hosted_page_enabled": true,
  "mode": "public",
  "enabled": false,
  "has_secret": false,
  "has_password": false,
  "token_version": 1,
  "max_accounts": 100,
  "accounts": [
    {
      "id": 1,
      "identifier_type": "email",
      "identifier": "support-lead@example.com",
      "label": "Support lead",
      "enabled": true,
      "last_login_at": null,
      "created_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "object": "chatbot_access",
  "id": 1
}

/v1/chatbots/{id}/access

Set a chatbot's hosted page access

Publishes or unpublishes the hosted agent page and sets who may open it. mode and enabled are required on every call; password and hosted_page_enabled keep their stored value when omitted. secret mode: the first switch to it, or regenerate_secret: true, mints a share secret and returns it once as secret; store it, it is never shown again. password mode needs a password, sent now or already stored; an empty string clears it. credentialed mode needs at least one enabled visitor login (POST /chatbots/{id}/access/accounts). revoke: true signs every visitor out by raising token_version. A body that would leave the gate unusable (password mode with no password, credentialed mode with no enabled login) is 422 VALIDATION_FAILED. It emits no webhook event.

Required scope: chatbots:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

id(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

idintegerRequired
The chatbot id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

Public /v1 access payload. Field set is pinned on this class so a dashboard FormRequest tweak cannot silently widen the public contract. hosted_page_enabled is deliberately part of it (owner decision 2026-09-19): an API key holding chatbots:write may publish / unpublish the hosted page like the dashboard does.

modestringRequired
Who may open the hosted page: public (anyone with the link), secret (the link plus a share secret), password (a shared password) or credentialed (a visitor login).
Possible valuespublicsecretpasswordcredentialed
enabledbooleanRequired
Whether the gate of mode is on. A disabled gate behaves like public; public is always stored as disabled.
passwordstringnullableOptional
The shared password of password mode, at least 8 characters. Omit it to keep the stored one; an empty string clears it. Refused in any other mode.
Min length: 8Max length: 200
regenerate_secretbooleanOptional
true mints a new share secret, returned once as secret. Only with mode: secret; switching to secret mode with no stored secret mints one anyway.
revokebooleanOptional
true signs every visitor out: issued visitor access tokens stop working (token_version rises).
hosted_page_enabledbooleanOptional
Publishes (true) or unpublishes (false) the hosted agent page. Omit it to keep the current value.

Responses

200
Success.
chatbot_idintegerRequired
The chatbot this access configuration belongs to.
handlestringRequired
The chatbot's public handle: its hosted page lives at /agent/{handle}.
hosted_page_enabledbooleanRequired
Whether the hosted agent page is published at all. While false the page is offline whatever mode says.
modestringRequired
Who may open the hosted page: public (anyone with the link), secret (the link plus the share secret), password (a shared password) or credentialed (one of the visitor logins in accounts).
Possible valuespublicsecretpasswordcredentialed
enabledbooleanRequired
Whether the gate of mode is on. Always false in public mode; a disabled gate behaves like public.
has_secretbooleanRequired
Whether a share secret is stored. The secret itself is returned once, by the PUT /chatbots/{id}/access that minted it.
has_passwordbooleanRequired
Whether a shared password is stored for password mode. The password is never returned.
token_versionintegerRequired
Revocation epoch of the visitor access tokens. PUT /chatbots/{id}/access with revoke: true raises it, which signs every visitor out.
max_accountsintegerRequired
How many visitor logins accounts may hold.
accountsarray of AgentAccessAccountResourceOptional
The visitor logins of credentialed mode, managed with POST and DELETE /chatbots/{id}/access/accounts.
objectstringRequired
Alwayschatbot_access
idintegerRequired
The chatbot id (the same value as chatbot_id).
secretstringOptional
The share secret, present only on the response of the request that minted it. It is never returned again.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X PUT 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/access' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "mode": "mode",
  "enabled": true,
  "password": "password",
  "regenerate_secret": true,
  "revoke": true,
  "hosted_page_enabled": true
}'

Response

Example 200 response

json

{
  "chatbot_id": 1,
  "handle": "acme-orders",
  "hosted_page_enabled": true,
  "mode": "credentialed",
  "enabled": false,
  "has_secret": false,
  "has_password": false,
  "token_version": 2,
  "max_accounts": 100,
  "accounts": [],
  "object": "chatbot_access",
  "id": 1
}

/v1/chatbots/{id}/activate

Activate a chatbot

Sets status to active, which puts the chatbot live on its website widget and hosted agent page, and returns it. Activating an already active chatbot succeeds and emits chatbot.activated again. It does not train the chatbot: check GET /chatbots/{id}/readiness.

Required scope: chatbots:write
Idempotency: Accepts Idempotency-Key
Webhook events: chatbot.activated
Rate limits

Before you call

id(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

idintegerRequired
The chatbot id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Responses

200
ChatbotResource
objectstringRequired
Alwayschatbot
idintegerRequired
The chatbot id, used in every /chatbots/{id} path and as chatbot_id elsewhere.
slugstringRequired
The public handle: the hosted agent page lives at /agent/{slug}. Unique across the platform; PUT /chatbots/{id}/handle changes it, a rename never does.
namestringRequired
Display name, unique within the account.
descriptionstringnullableRequired
Your own description of the chatbot; null when none.
avatar_urlstringnullableRequired
Absolute URL of the avatar image; null when the chatbot has none.
colorstringRequired
Flat header colour: a theme token or a #rrggbb hex. Used when header_theme is flat.
primary_languagestringRequired
The language the chatbot answers in, e.g. English.
supported_languagesobjectRequired
Further languages the chatbot is set up for; [] when none.
text_directionstringRequired
LTR or RTL, derived from primary_language.
statusstringRequired
Lifecycle status. The widget and hosted page serve only an active chatbot; a new one is draft.
Possible valuesactiveinactivedraft
training_statusstringRequired
Where training of the chatbot's knowledge stands. completed once every source is trained; never_trained before any.
Possible valuesnever_trainedpendingtrainingupdatingneeds_retrainingcompletedfailed
cache_responsesbooleanRequired
Whether a repeated question may be answered from the response cache instead of a new model call.
last_training_datestringnullableRequired
When training last completed (ISO 8601, UTC); null before the first.
last_active_atstringnullableRequired
When the chatbot last answered a chat turn (ISO 8601, UTC); null before the first.
template_idintegernullableRequired
The catalogue template the chatbot was created from; null when none.
response_lengthstringRequired
Answer length preset: Short Response or Long Response.
audiencestringRequired
Who the chatbot serves: customers (it speaks for the business) or personal (the owner's private assistant). customers unless set at creation.
knowledge_modestringRequired
How far answers may step outside the knowledge base: strict (knowledge only) or general (general knowledge when the knowledge base has nothing). strict unless set at creation.
welcome_messagestringnullableRequired
The first message the widget and hosted page show; null for the default greeting.
fallback_messagestringnullableRequired
The reply sent when the chatbot cannot produce an answer; null for the platform default.
custom_instructionsobjectRequired
Your extra instructions for every answer, one string per instruction; [] when none. The plan caps how many.
enable_handoffbooleanRequired
Whether the chatbot may hand a conversation to a human.
training_configobjectRequired
Training and retrieval tuning set through PATCH /chatbots/{id}; [] when never set.
gradient_stylestringRequired
Header gradient: a theme token or a #rrggbb,#rrggbb pair. Used when header_theme is gradient.
header_themestringRequired
Header fill: gradient (uses gradient_style) or flat (uses color).
is_image_avatarbooleanRequired
Whether the avatar is an uploaded image (POST /chatbots/{id}/avatar).
settingsobjectRequired
The widget look-and-behaviour keys set on the chatbot (PUT /chatbots/{chatbotId}/widget). A key never set is absent.
lead_captureobjectnullableRequired
Lead capture: whether the widget asks visitors for contact details (enabled), when (trigger), which fields, and whether they may skip it; null when never configured.
allowed_domainsobjectRequired
Hostnames whose pages may load the widget; [] lets it load on any site. Managed with the /chatbots/{chatbotId}/widget/domains operations.
created_atstringnullableRequired
When the chatbot was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the chatbot last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/activate' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "chatbot",
  "id": 1,
  "slug": "orders-assistant",
  "name": "Orders Assistant",
  "description": "Tracks orders and deliveries.",
  "avatar_url": null,
  "color": "bg-indigo-500",
  "primary_language": "English",
  "supported_languages": [],
  "text_direction": "LTR",
  "status": "active",
  "training_status": "never_trained",
  "cache_responses": true,
  "last_training_date": null,
  "last_active_at": null,
  "template_id": null,
  "response_length": "Short Response",
  "audience": "customers",
  "knowledge_mode": "strict",
  "welcome_message": "Hi! Ask me about orders, shipping or refunds.",
  "fallback_message": null,
  "custom_instructions": [],
  "enable_handoff": false,
  "training_config": [],
  "gradient_style": "from-indigo-600 to-blue-600",
  "header_theme": "gradient",
  "is_image_avatar": false,
  "settings": {
    "widget_position": "bottom-left"
  },
  "lead_capture": null,
  "allowed_domains": [],
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/chatbots/{id}/deactivate

Deactivate a chatbot

Sets status to inactive, which takes the chatbot offline on its website widget and hosted agent page, and returns it. Its knowledge, conversations and channels are kept, and POST /chat still answers for it. Deactivating an inactive chatbot succeeds and emits chatbot.deactivated again.

Required scope: chatbots:write
Idempotency: Accepts Idempotency-Key
Webhook events: chatbot.deactivated
Rate limits

Before you call

id(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

idintegerRequired
The chatbot id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Responses

200
ChatbotResource
objectstringRequired
Alwayschatbot
idintegerRequired
The chatbot id, used in every /chatbots/{id} path and as chatbot_id elsewhere.
slugstringRequired
The public handle: the hosted agent page lives at /agent/{slug}. Unique across the platform; PUT /chatbots/{id}/handle changes it, a rename never does.
namestringRequired
Display name, unique within the account.
descriptionstringnullableRequired
Your own description of the chatbot; null when none.
avatar_urlstringnullableRequired
Absolute URL of the avatar image; null when the chatbot has none.
colorstringRequired
Flat header colour: a theme token or a #rrggbb hex. Used when header_theme is flat.
primary_languagestringRequired
The language the chatbot answers in, e.g. English.
supported_languagesobjectRequired
Further languages the chatbot is set up for; [] when none.
text_directionstringRequired
LTR or RTL, derived from primary_language.
statusstringRequired
Lifecycle status. The widget and hosted page serve only an active chatbot; a new one is draft.
Possible valuesactiveinactivedraft
training_statusstringRequired
Where training of the chatbot's knowledge stands. completed once every source is trained; never_trained before any.
Possible valuesnever_trainedpendingtrainingupdatingneeds_retrainingcompletedfailed
cache_responsesbooleanRequired
Whether a repeated question may be answered from the response cache instead of a new model call.
last_training_datestringnullableRequired
When training last completed (ISO 8601, UTC); null before the first.
last_active_atstringnullableRequired
When the chatbot last answered a chat turn (ISO 8601, UTC); null before the first.
template_idintegernullableRequired
The catalogue template the chatbot was created from; null when none.
response_lengthstringRequired
Answer length preset: Short Response or Long Response.
audiencestringRequired
Who the chatbot serves: customers (it speaks for the business) or personal (the owner's private assistant). customers unless set at creation.
knowledge_modestringRequired
How far answers may step outside the knowledge base: strict (knowledge only) or general (general knowledge when the knowledge base has nothing). strict unless set at creation.
welcome_messagestringnullableRequired
The first message the widget and hosted page show; null for the default greeting.
fallback_messagestringnullableRequired
The reply sent when the chatbot cannot produce an answer; null for the platform default.
custom_instructionsobjectRequired
Your extra instructions for every answer, one string per instruction; [] when none. The plan caps how many.
enable_handoffbooleanRequired
Whether the chatbot may hand a conversation to a human.
training_configobjectRequired
Training and retrieval tuning set through PATCH /chatbots/{id}; [] when never set.
gradient_stylestringRequired
Header gradient: a theme token or a #rrggbb,#rrggbb pair. Used when header_theme is gradient.
header_themestringRequired
Header fill: gradient (uses gradient_style) or flat (uses color).
is_image_avatarbooleanRequired
Whether the avatar is an uploaded image (POST /chatbots/{id}/avatar).
settingsobjectRequired
The widget look-and-behaviour keys set on the chatbot (PUT /chatbots/{chatbotId}/widget). A key never set is absent.
lead_captureobjectnullableRequired
Lead capture: whether the widget asks visitors for contact details (enabled), when (trigger), which fields, and whether they may skip it; null when never configured.
allowed_domainsobjectRequired
Hostnames whose pages may load the widget; [] lets it load on any site. Managed with the /chatbots/{chatbotId}/widget/domains operations.
created_atstringnullableRequired
When the chatbot was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the chatbot last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/deactivate' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "chatbot",
  "id": 1,
  "slug": "orders-assistant",
  "name": "Orders Assistant",
  "description": "Tracks orders and deliveries.",
  "avatar_url": null,
  "color": "bg-indigo-500",
  "primary_language": "English",
  "supported_languages": [],
  "text_direction": "LTR",
  "status": "inactive",
  "training_status": "never_trained",
  "cache_responses": true,
  "last_training_date": null,
  "last_active_at": null,
  "template_id": null,
  "response_length": "Short Response",
  "audience": "customers",
  "knowledge_mode": "strict",
  "welcome_message": "Hi! Ask me about orders, shipping or refunds.",
  "fallback_message": null,
  "custom_instructions": [],
  "enable_handoff": false,
  "training_config": [],
  "gradient_style": "from-indigo-600 to-blue-600",
  "header_theme": "gradient",
  "is_image_avatar": false,
  "settings": {
    "widget_position": "bottom-left"
  },
  "lead_capture": null,
  "allowed_domains": [],
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/chatbots/{id}/handle

Change a chatbot's handle

Sets the chatbot's public handle (slug), which is the address of its hosted agent page: /agent/{handle}. Handles are unique across the platform, so one another chatbot holds — on any account — is 422 VALIDATION_FAILED on handle. Setting the current handle again changes nothing. The old address stops working at once: update every link you shared. It emits no webhook event.

Required scope: chatbots:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

id(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

idintegerRequired
The chatbot id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

Public /v1 update chatbot handle payload. Field set is pinned on this class so a dashboard FormRequest tweak cannot silently widen the public contract.

handlestringRequired
The new handle: lowercase letters and digits with single inner hyphens, 3–40 characters, not all digits and not a reserved word. Unique across the platform: one another chatbot holds is 422 VALIDATION_FAILED. So is one another account released — by renaming or deleting its chatbot — in the last 90 days by default; a handle your account released stays yours to take back.
Min length: 3Max length: 40Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

Responses

200
ChatbotResource
objectstringRequired
Alwayschatbot
idintegerRequired
The chatbot id, used in every /chatbots/{id} path and as chatbot_id elsewhere.
slugstringRequired
The public handle: the hosted agent page lives at /agent/{slug}. Unique across the platform; PUT /chatbots/{id}/handle changes it, a rename never does.
namestringRequired
Display name, unique within the account.
descriptionstringnullableRequired
Your own description of the chatbot; null when none.
avatar_urlstringnullableRequired
Absolute URL of the avatar image; null when the chatbot has none.
colorstringRequired
Flat header colour: a theme token or a #rrggbb hex. Used when header_theme is flat.
primary_languagestringRequired
The language the chatbot answers in, e.g. English.
supported_languagesobjectRequired
Further languages the chatbot is set up for; [] when none.
text_directionstringRequired
LTR or RTL, derived from primary_language.
statusstringRequired
Lifecycle status. The widget and hosted page serve only an active chatbot; a new one is draft.
Possible valuesactiveinactivedraft
training_statusstringRequired
Where training of the chatbot's knowledge stands. completed once every source is trained; never_trained before any.
Possible valuesnever_trainedpendingtrainingupdatingneeds_retrainingcompletedfailed
cache_responsesbooleanRequired
Whether a repeated question may be answered from the response cache instead of a new model call.
last_training_datestringnullableRequired
When training last completed (ISO 8601, UTC); null before the first.
last_active_atstringnullableRequired
When the chatbot last answered a chat turn (ISO 8601, UTC); null before the first.
template_idintegernullableRequired
The catalogue template the chatbot was created from; null when none.
response_lengthstringRequired
Answer length preset: Short Response or Long Response.
audiencestringRequired
Who the chatbot serves: customers (it speaks for the business) or personal (the owner's private assistant). customers unless set at creation.
knowledge_modestringRequired
How far answers may step outside the knowledge base: strict (knowledge only) or general (general knowledge when the knowledge base has nothing). strict unless set at creation.
welcome_messagestringnullableRequired
The first message the widget and hosted page show; null for the default greeting.
fallback_messagestringnullableRequired
The reply sent when the chatbot cannot produce an answer; null for the platform default.
custom_instructionsobjectRequired
Your extra instructions for every answer, one string per instruction; [] when none. The plan caps how many.
enable_handoffbooleanRequired
Whether the chatbot may hand a conversation to a human.
training_configobjectRequired
Training and retrieval tuning set through PATCH /chatbots/{id}; [] when never set.
gradient_stylestringRequired
Header gradient: a theme token or a #rrggbb,#rrggbb pair. Used when header_theme is gradient.
header_themestringRequired
Header fill: gradient (uses gradient_style) or flat (uses color).
is_image_avatarbooleanRequired
Whether the avatar is an uploaded image (POST /chatbots/{id}/avatar).
settingsobjectRequired
The widget look-and-behaviour keys set on the chatbot (PUT /chatbots/{chatbotId}/widget). A key never set is absent.
lead_captureobjectnullableRequired
Lead capture: whether the widget asks visitors for contact details (enabled), when (trigger), which fields, and whether they may skip it; null when never configured.
allowed_domainsobjectRequired
Hostnames whose pages may load the widget; [] lets it load on any site. Managed with the /chatbots/{chatbotId}/widget/domains operations.
created_atstringnullableRequired
When the chatbot was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the chatbot last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X PUT 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/handle' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "handle": "handle"
}'

Response

Example 200 response

json

{
  "object": "chatbot",
  "id": 1,
  "slug": "acme-orders",
  "name": "Orders Assistant",
  "description": "Tracks orders and deliveries.",
  "avatar_url": null,
  "color": "bg-indigo-500",
  "primary_language": "English",
  "supported_languages": [],
  "text_direction": "LTR",
  "status": "inactive",
  "training_status": "never_trained",
  "cache_responses": true,
  "last_training_date": null,
  "last_active_at": null,
  "template_id": null,
  "response_length": "Short Response",
  "audience": "customers",
  "knowledge_mode": "strict",
  "welcome_message": "Hi! Ask me about orders, shipping or refunds.",
  "fallback_message": null,
  "custom_instructions": [],
  "enable_handoff": false,
  "training_config": [],
  "gradient_style": "from-indigo-600 to-blue-600",
  "header_theme": "gradient",
  "is_image_avatar": false,
  "settings": {
    "widget_position": "bottom-left"
  },
  "lead_capture": null,
  "allowed_domains": [],
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/chatbots/{id}/access/accounts

Add a hosted page login

Creates a visitor login for the chatbot's credentialed hosted page and returns it with 201 (never the password). The identifier must be unique on the chatbot, and the chatbot holds at most max_accounts logins; either refusal is 422 VALIDATION_FAILED on identifier. The login only gates the page once mode is credentialed. It emits no webhook event.

Required scope: chatbots:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

id(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

idintegerRequired
The chatbot id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

Public /v1 store agent access account payload. Field set is pinned on this class so a dashboard FormRequest tweak cannot silently widen the public contract.

identifier_typestringRequired
What the visitor signs in with: username, email or phone.
Possible valuesusernameemailphone
identifierstringRequired
The username, email address or phone number, at most 190 characters, in the format identifier_type names. Unique on the chatbot.
Max length: 190
labelstringnullableOptional
Your own note on who this login is for, at most 120 characters.
Max length: 120
passwordstringRequired
The visitor's password, 8–200 characters. Stored hashed and never returned.
Min length: 8Max length: 200
enabledbooleanOptional
Whether the login may sign in. Defaults to true.

Responses

201
AgentAccessAccount
objectstringRequired
Alwaysagent_access_account
idintegerRequired
The access account id, for DELETE /chatbots/{id}/access/accounts/{accountId}.
identifier_typestringRequired
What the visitor signs in with: a username, an email or a phone number.
Possible valuesusernameemailphone
identifierstringRequired
The username, email or phone number the visitor signs in with.
labelstringnullableRequired
Your own note on who this login is for; null when none.
enabledbooleanRequired
Whether this login may sign in.
last_login_atstringnullableRequired
When the visitor last signed in with this login (ISO 8601); null when never.
created_atstringnullableRequired
When the login was created (ISO 8601).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/access/accounts' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "identifier_type": "identifier_type",
  "identifier": "identifier",
  "label": "label",
  "password": "password",
  "enabled": true
}'

Response

Example 201 response

json

{
  "object": "agent_access_account",
  "id": 1,
  "identifier_type": "email",
  "identifier": "reviewer@example.com",
  "label": "QA reviewer",
  "enabled": true,
  "last_login_at": null,
  "created_at": "2026-01-01T00:00:00+00:00"
}

/v1/chatbots/{id}/access/accounts/{accountId}

Remove a hosted page login

Deletes one visitor login; a visitor signed in with it loses access. Removing the last enabled login of a chatbot in credentialed mode leaves no one able to open the page until you add another or change the mode. It emits no webhook event.

Required scope: chatbots:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

id(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.
accountId(path)Access account id
Integer.
Placeholder in the samples: <ACCOUNT_ID>
Get it from
- POST /v1/chatbots/{id}/access/accounts returns it as id
- GET /v1/chatbots/{id}/access returns it as accounts[].id

Path parameters

idintegerRequired
The chatbot id.
accountIdintegerRequired
The access account id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Responses

200
Success.
objectstringRequired
Alwaysagent_access_account
idintegerRequired
deletedbooleanRequired
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X DELETE 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/access/accounts/<ACCOUNT_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "agent_access_account",
  "id": 1,
  "deleted": true
}

/v1/chatbots/{id}/avatar

Upload a chatbot avatar

Uploads an image as multipart/form-data (field file), makes it the chatbot's avatar and returns the chatbot with the new avatar_url and is_image_avatar: true. The previous uploaded avatar is deleted when no other chatbot uses it.

Required scope: chatbots:write
Idempotency: Accepts Idempotency-Key
Webhook events: chatbot.updated
Rate limits

Before you call

id(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

idintegerRequired
The chatbot id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

filestringRequired
The image, sent as multipart/form-data: JPEG, PNG, GIF or WebP, by default at most 5 MB and 4096 × 4096 pixels.
Format: binary

Responses

200
ChatbotResource
objectstringRequired
Alwayschatbot
idintegerRequired
The chatbot id, used in every /chatbots/{id} path and as chatbot_id elsewhere.
slugstringRequired
The public handle: the hosted agent page lives at /agent/{slug}. Unique across the platform; PUT /chatbots/{id}/handle changes it, a rename never does.
namestringRequired
Display name, unique within the account.
descriptionstringnullableRequired
Your own description of the chatbot; null when none.
avatar_urlstringnullableRequired
Absolute URL of the avatar image; null when the chatbot has none.
colorstringRequired
Flat header colour: a theme token or a #rrggbb hex. Used when header_theme is flat.
primary_languagestringRequired
The language the chatbot answers in, e.g. English.
supported_languagesobjectRequired
Further languages the chatbot is set up for; [] when none.
text_directionstringRequired
LTR or RTL, derived from primary_language.
statusstringRequired
Lifecycle status. The widget and hosted page serve only an active chatbot; a new one is draft.
Possible valuesactiveinactivedraft
training_statusstringRequired
Where training of the chatbot's knowledge stands. completed once every source is trained; never_trained before any.
Possible valuesnever_trainedpendingtrainingupdatingneeds_retrainingcompletedfailed
cache_responsesbooleanRequired
Whether a repeated question may be answered from the response cache instead of a new model call.
last_training_datestringnullableRequired
When training last completed (ISO 8601, UTC); null before the first.
last_active_atstringnullableRequired
When the chatbot last answered a chat turn (ISO 8601, UTC); null before the first.
template_idintegernullableRequired
The catalogue template the chatbot was created from; null when none.
response_lengthstringRequired
Answer length preset: Short Response or Long Response.
audiencestringRequired
Who the chatbot serves: customers (it speaks for the business) or personal (the owner's private assistant). customers unless set at creation.
knowledge_modestringRequired
How far answers may step outside the knowledge base: strict (knowledge only) or general (general knowledge when the knowledge base has nothing). strict unless set at creation.
welcome_messagestringnullableRequired
The first message the widget and hosted page show; null for the default greeting.
fallback_messagestringnullableRequired
The reply sent when the chatbot cannot produce an answer; null for the platform default.
custom_instructionsobjectRequired
Your extra instructions for every answer, one string per instruction; [] when none. The plan caps how many.
enable_handoffbooleanRequired
Whether the chatbot may hand a conversation to a human.
training_configobjectRequired
Training and retrieval tuning set through PATCH /chatbots/{id}; [] when never set.
gradient_stylestringRequired
Header gradient: a theme token or a #rrggbb,#rrggbb pair. Used when header_theme is gradient.
header_themestringRequired
Header fill: gradient (uses gradient_style) or flat (uses color).
is_image_avatarbooleanRequired
Whether the avatar is an uploaded image (POST /chatbots/{id}/avatar).
settingsobjectRequired
The widget look-and-behaviour keys set on the chatbot (PUT /chatbots/{chatbotId}/widget). A key never set is absent.
lead_captureobjectnullableRequired
Lead capture: whether the widget asks visitors for contact details (enabled), when (trigger), which fields, and whether they may skip it; null when never configured.
allowed_domainsobjectRequired
Hostnames whose pages may load the widget; [] lets it load on any site. Managed with the /chatbots/{chatbotId}/widget/domains operations.
created_atstringnullableRequired
When the chatbot was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the chatbot last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/avatar' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "file": "file"
}'

Response

Example 200 response

json

{
  "object": "chatbot",
  "id": 1,
  "slug": "acme-orders",
  "name": "Orders Assistant",
  "description": "Tracks orders and deliveries.",
  "avatar_url": "https://api.agentency.test/uploads/avatars/u1/3f/2a/9c/3f2a9c4e-6b1d-4e8a-9f27-5c0d8e1b7a46.png",
  "color": "bg-indigo-500",
  "primary_language": "English",
  "supported_languages": [],
  "text_direction": "LTR",
  "status": "inactive",
  "training_status": "never_trained",
  "cache_responses": true,
  "last_training_date": null,
  "last_active_at": null,
  "template_id": null,
  "response_length": "Short Response",
  "audience": "customers",
  "knowledge_mode": "strict",
  "welcome_message": "Hi! Ask me about orders, shipping or refunds.",
  "fallback_message": null,
  "custom_instructions": [],
  "enable_handoff": false,
  "training_config": [],
  "gradient_style": "from-indigo-600 to-blue-600",
  "header_theme": "gradient",
  "is_image_avatar": true,
  "settings": {
    "widget_position": "bottom-left"
  },
  "lead_capture": null,
  "allowed_domains": [],
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/chatbots/{id}/avatar

Remove a chatbot avatar

Clears the chatbot's avatar (avatar_url: null, is_image_avatar: false) so the widget shows its default, and returns the chatbot. The uploaded image is deleted when no other chatbot uses it.

Required scope: chatbots:write
Idempotency: Accepts Idempotency-Key
Webhook events: chatbot.updated
Rate limits

Before you call

id(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

idintegerRequired
The chatbot id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Responses

200
ChatbotResource
objectstringRequired
Alwayschatbot
idintegerRequired
The chatbot id, used in every /chatbots/{id} path and as chatbot_id elsewhere.
slugstringRequired
The public handle: the hosted agent page lives at /agent/{slug}. Unique across the platform; PUT /chatbots/{id}/handle changes it, a rename never does.
namestringRequired
Display name, unique within the account.
descriptionstringnullableRequired
Your own description of the chatbot; null when none.
avatar_urlstringnullableRequired
Absolute URL of the avatar image; null when the chatbot has none.
colorstringRequired
Flat header colour: a theme token or a #rrggbb hex. Used when header_theme is flat.
primary_languagestringRequired
The language the chatbot answers in, e.g. English.
supported_languagesobjectRequired
Further languages the chatbot is set up for; [] when none.
text_directionstringRequired
LTR or RTL, derived from primary_language.
statusstringRequired
Lifecycle status. The widget and hosted page serve only an active chatbot; a new one is draft.
Possible valuesactiveinactivedraft
training_statusstringRequired
Where training of the chatbot's knowledge stands. completed once every source is trained; never_trained before any.
Possible valuesnever_trainedpendingtrainingupdatingneeds_retrainingcompletedfailed
cache_responsesbooleanRequired
Whether a repeated question may be answered from the response cache instead of a new model call.
last_training_datestringnullableRequired
When training last completed (ISO 8601, UTC); null before the first.
last_active_atstringnullableRequired
When the chatbot last answered a chat turn (ISO 8601, UTC); null before the first.
template_idintegernullableRequired
The catalogue template the chatbot was created from; null when none.
response_lengthstringRequired
Answer length preset: Short Response or Long Response.
audiencestringRequired
Who the chatbot serves: customers (it speaks for the business) or personal (the owner's private assistant). customers unless set at creation.
knowledge_modestringRequired
How far answers may step outside the knowledge base: strict (knowledge only) or general (general knowledge when the knowledge base has nothing). strict unless set at creation.
welcome_messagestringnullableRequired
The first message the widget and hosted page show; null for the default greeting.
fallback_messagestringnullableRequired
The reply sent when the chatbot cannot produce an answer; null for the platform default.
custom_instructionsobjectRequired
Your extra instructions for every answer, one string per instruction; [] when none. The plan caps how many.
enable_handoffbooleanRequired
Whether the chatbot may hand a conversation to a human.
training_configobjectRequired
Training and retrieval tuning set through PATCH /chatbots/{id}; [] when never set.
gradient_stylestringRequired
Header gradient: a theme token or a #rrggbb,#rrggbb pair. Used when header_theme is gradient.
header_themestringRequired
Header fill: gradient (uses gradient_style) or flat (uses color).
is_image_avatarbooleanRequired
Whether the avatar is an uploaded image (POST /chatbots/{id}/avatar).
settingsobjectRequired
The widget look-and-behaviour keys set on the chatbot (PUT /chatbots/{chatbotId}/widget). A key never set is absent.
lead_captureobjectnullableRequired
Lead capture: whether the widget asks visitors for contact details (enabled), when (trigger), which fields, and whether they may skip it; null when never configured.
allowed_domainsobjectRequired
Hostnames whose pages may load the widget; [] lets it load on any site. Managed with the /chatbots/{chatbotId}/widget/domains operations.
created_atstringnullableRequired
When the chatbot was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the chatbot last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X DELETE 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/avatar' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "chatbot",
  "id": 1,
  "slug": "acme-orders",
  "name": "Orders Assistant",
  "description": "Tracks orders and deliveries.",
  "avatar_url": null,
  "color": "bg-indigo-500",
  "primary_language": "English",
  "supported_languages": [],
  "text_direction": "LTR",
  "status": "inactive",
  "training_status": "never_trained",
  "cache_responses": true,
  "last_training_date": null,
  "last_active_at": null,
  "template_id": null,
  "response_length": "Short Response",
  "audience": "customers",
  "knowledge_mode": "strict",
  "welcome_message": "Hi! Ask me about orders, shipping or refunds.",
  "fallback_message": null,
  "custom_instructions": [],
  "enable_handoff": false,
  "training_config": [],
  "gradient_style": "from-indigo-600 to-blue-600",
  "header_theme": "gradient",
  "is_image_avatar": false,
  "settings": {
    "widget_position": "bottom-left"
  },
  "lead_capture": null,
  "allowed_domains": [],
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

About Chatbots

IDs on this page

/v1/chatbots

Query parameters

Responses

See also

Request

Response

/v1/chatbots

Header parameters

Request body

Responses

See also

Request

Response

/v1/chatbots/by_handle/{handle}

Path parameters

Responses

See also

Request

Response

/v1/chatbots/{id}

Path parameters

Responses

See also

Request

Response

/v1/chatbots/{id}

Path parameters

Header parameters

Request body

Responses

See also

Request

Response

/v1/chatbots/{id}

Path parameters

Header parameters

Responses

See also

Request

Response

/v1/chatbots/{id}/readiness

Path parameters

Responses

See also

Request

Response

/v1/chatbots/{id}/access

Path parameters

Responses

See also

Request

Response

/v1/chatbots/{id}/access

Path parameters

Header parameters

Request body

Responses

See also

Request

Response

/v1/chatbots/{id}/activate

Path parameters

Header parameters

Responses

See also

Request

Response

/v1/chatbots/{id}/deactivate

Path parameters

Header parameters

Responses

See also

Request

Response

/v1/chatbots/{id}/handle

Path parameters

Header parameters

Request body