Chatbots

List chatbots

Returns a cursor-paginated list of chatbots owned by the API key account. Filter by status, training_status, and search. Supports limit, starting_after, ending_before, created[gte], created[lte], sort, and expand[].

Required scopechatbots:read

{
  "object": "list",
  "data": [
    {
      "object": "chatbot",
      "id": 1,
      "slug": "turcotte-rath-bot-54229",
      "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",
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/chatbots"
}

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

Create a chatbot

Create a chatbot. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopechatbots:write

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",
  "primary_language": "primary_language",
  "text_direction": "text_direction",
  "response_length": "response_length",
  "cache_responses": "cache_responses",
  "welcome_message": "welcome_message"
}'

Retrieve a chatbot by handle

Resolves a chatbot from its public handle when the client does not have the numeric id. Returns 404 NOT_FOUND when the handle is unknown on this account.

Required scopechatbots:read

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

Retrieve a chatbot

Retrieve a chatbot. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopechatbots:read

{
  "object": "chatbot",
  "id": 1,
  "slug": "turcotte-rath-bot-54229",
  "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",
  "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"
}

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

Update a chatbot

Update a chatbot. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopechatbots:write

curl -X PATCH https://api.agentency.com/v1/chatbots/{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",
  "welcome_message": "welcome_message",
  "fallback_message": "fallback_message"
}'

Delete a chatbot

Delete a chatbot. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopechatbots:write

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

Readiness chatbot

Readiness chatbot. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopechatbots:read

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

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

Access chatbot

Access chatbot. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopechatbots:read

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

Update access chatbot

Update access chatbot. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopechatbots:write

curl -X PUT https://api.agentency.com/v1/chatbots/{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
}'

Activate chatbot

Activate chatbot. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopechatbots:write

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

Deactivate chatbot

Deactivate chatbot. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopechatbots:write

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

Update handle chatbot

Update handle chatbot. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopechatbots:write

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

Grant access chatbot

Grant access chatbot. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopechatbots:write

curl -X POST https://api.agentency.com/v1/chatbots/{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
}'

Revoke access chatbot

Revoke access chatbot. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopechatbots:write

curl -X DELETE https://api.agentency.com/v1/chatbots/{id}/access/accounts/{accountId} \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Upload avatar chatbot

Upload avatar chatbot. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopechatbots:write

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

Delete avatar chatbot

Delete avatar chatbot. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopechatbots:write

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