← Back to app

API & MCP

Control your chatbot from your own code or from AI assistants.

Overview#

Chatbotty can be used and managed from outside the dashboard in two ways: the REST API for your own code and the MCP connector for AI assistants such as Claude. Both work with one chatbot at a time and use the same API keys. Start with Authentication.

Basics

ItemValue
REST base URLhttps://www.chatbotty.ai/api/v1
MCP server URLhttps://www.chatbotty.ai/api/mcp
FormatJSON over HTTPS
AuthenticationAuthorization: Bearer YOUR_API_KEY
Scope of a keyOne key belongs to exactly one chatbot; the chatbot is never sent in the request, it is derived from the key

Which one to use

  • REST API - you write code that sends chat messages or manages documents, conversations, tickets and webhook actions. See Chatbot and the following endpoint sections.
  • MCP connector - you connect an AI assistant and let it work with the chatbot without coding. See MCP connector and MCP clients.

Plans

API keys, the REST API and the MCP connector are available on every plan: Free, Evaluation, Support and Automate. Individual features depend on the plan.

FeatureFreeEvaluationSupportAutomate
Chat, documents, conversations, analyticsYesYesYesYes
TicketsNoYesYesYes
Webhook actionsNoYesNoYes
Document import from a web URLNoYesYesYes

A call to a feature that is not in your plan returns 403 FORBIDDEN. The MCP connector does not offer such tools at all. A plan change applies to the next request.

Quota

  • Only messages sent through chat (REST POST /chat or the MCP tool send_message) count against the monthly message quota, exactly like widget messages.
  • Other calls (documents, conversations, analytics, tickets, webhook actions) do not use the quota.
  • When the quota is used up, the chat call returns 403 QUOTA_EXCEEDED. Check the remaining quota with GET /chatbot.
  • Keys work regardless of the chatbot's allowed domains and even when the chatbot is inactive for the widget (except sending chat messages, which an inactive chatbot refuses with 404 NOT_FOUND).

Response format

Every REST response uses the same envelope. Errors are described in Errors.

{ "success": true, "data": { }, "timestamp": "2026-01-01T10:00:00.000Z" }

Authentication#

Every request must carry an API key of the chatbot as a Bearer token. The same key works for the REST API and for the MCP connector.

curl -H "Authorization: Bearer YOUR_API_KEY" https://www.chatbotty.ai/api/v1/chatbot

API keys

ItemValue
FormatA random 64-character hexadecimal string
ScopeOne chatbot per key
LimitUp to 50 keys per chatbot (inactive keys count too)
StorageOnly a hash is stored; the full key is shown once, right after creation

Treat keys like passwords: never share them and never put them in client-side code.

Manage keys in the dashboard

  1. Open API & MCP in the sidebar.
  2. On the card of your chatbot, click Create new API key, enter a name (for example "Production app") and click Create.
  3. Copy the key immediately. It cannot be shown again ("Copy this key now. You won't be able to see it again.").

Afterwards the list shows the key name, its first 12 characters and Last used.

ActionEffect
DeactivateThe key stops working at once; Activate turns it back on
DeleteThe key is removed permanently; apps using it stop working immediately

Keys created by connecting an AI assistant are labelled MCP connector. Deleting such a key disconnects the assistant. Connecting the same assistant to the same chatbot again replaces its old key.

Authentication errors

SituationResponse
Header missing or malformed401 UNAUTHORIZED "Missing or invalid Authorization header"
Unknown or deactivated key401 UNAUTHORIZED "Invalid or inactive API key"

See Errors for all codes and Rate limits for request limits.

Rate limits#

Limits apply per API key and per minute. Every class of endpoints has its own counter, so many writes do not use up the budget for reads.

REST API

ClassEndpointsLimit per minute
ChatPOST /chat60
ReadAll other GET endpoints except analytics (including GET /chatbot)120
WritePOST, PATCH, DELETE endpoints60
AnalyticsGET /analytics/summary, /analytics/timeseries, /analytics/top-queries60
Webhook testPOST /webhooks/{id}/test20

Additional limit: POST /documents/upload-url issues at most 50 upload URLs per chatbot within 2 hours.

MCP connector

The MCP endpoint allows 300 requests per minute per key. Each tool call is then also subject to the REST limit of the endpoint it uses, and send_message uses the message quota.

When you exceed a limit

The API returns 429 RATE_LIMITED with a message such as "Rate limit exceeded. Maximum 60 requests per minute per API key." Wait for the next minute and retry, ideally with a growing delay.

Rate limits are separate from the monthly message quota; see Overview and Errors.

Chatbot#

Identify the chatbot that your API key belongs to and check its plan and quota before you start working with it.

GET /chatbot

ItemValue
Method and pathGET https://www.chatbotty.ai/api/v1/chatbot
ParametersNone
Rate limitRead class (see Rate limits)
QuotaNot used
MCP toolget_chatbot_info

Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "CycleZone",
    "description": "Customer care chatbot",
    "is_active": true,
    "language": "auto",
    "timezone": "America/New_York",
    "handoff_contact": "info@example.com",
    "created_at": "2026-01-01T10:00:00.000Z",
    "dashboard_url": "https://www.chatbotty.ai/dashboard/chatbots/uuid",
    "plan": "Automate",
    "message_quota": { "used": 622, "monthly_limit": 9000, "extra_messages": 0 },
    "features": { "tickets": true, "upload_from_url": true, "webhook_actions": true },
    "knowledge_base": {
      "documents_total": 1,
      "documents_by_status": { "pending": 0, "processing": 0, "completed": 1, "failed": 0 },
      "last_updated_at": "2026-01-01T10:00:00.000Z"
    }
  }
}

Notes

  • plan and message_quota belong to the account owner; the quota is shared by all chatbots of the account.
  • features shows which plan-dependent features this key can use.
  • handoff_contact is the contact the chatbot gives when it does not know the answer (read-only here; null when not set).
  • last_updated_at is the time of the newest uploaded document.

Chat#

Send a message to the chatbot and receive its answer, exactly like a visitor in the widget.

POST /chat

ItemValue
Method and pathPOST https://www.chatbotty.ai/api/v1/chat
Rate limitChat class: 60 per minute
QuotaOne message per call; over the quota the call returns 403 QUOTA_EXCEEDED
MCP toolsend_message

Request body

FieldRequiredDescription
messageYesThe visitor's question (non-empty text)
conversation_idNoContinues an existing conversation; omit it to start a new one
optionsNoOptional object; not needed for normal use

If conversation_id does not exist or belongs to another chatbot, the call returns 400 CONVERSATION_NOT_FOUND. A chatbot that is not active returns 404 NOT_FOUND.

Response

{
  "success": true,
  "data": {
    "message": "Our warranty is two years.",
    "conversation_id": "uuid",
    "sources": [{ "content": "...", "similarity": 0.87 }],
    "metadata": {
      "tokensUsed": 312,
      "cached": false,
      "responseTime": 1240,
      "searchResults": 3,
      "quality": "answered",
      "confidence": 0.87,
      "tools_executed": [{ "name": "get_weather", "ok": true }]
    }
  }
}

Conversation context

The first call creates a conversation and returns its conversation_id. Send that id with every following message to keep the context. Conversations created through the API appear in the dashboard with the source api.

tools_executed

metadata.tools_executed lists the tools the chatbot called while answering (webhook actions, support ticket creation). Each item has name, ok and, on failure, a short code such as webhook_timeout, webhook_redirect, webhook_blocked or invalid_args. An empty list means no tool was called. Use it to verify that a webhook action really ran.

Documents#

Manage the knowledge base of the chatbot: upload, read, edit, list and delete documents. These calls do not use the message quota.

Endpoints

Method and pathDescriptionKey parametersMCP tool
GET /documentsList documentslimit (default 20, max 100), offset, statuslist_documents
POST /documentsUpload a document; returns 202See belowupload_document
POST /documents/upload-urlGet a signed URL for a large or local filefilenamecreate_upload_url
GET /documents/{id}Status and details of one document-get_document
DELETE /documents/{id}Delete a document-delete_document
GET /documents/{id}/contentRead the text, pagedoffset, limit (default 20000, max 50000)read_document
PATCH /documents/{id}/contentEdit a .md or .txt documentedits, append, expected_hashedit_document, append_to_document

Limits: GET calls use the read limit, the others the write limit (see Rate limits).

Upload

Allowed types: .pdf, .docx, .txt, .md, up to 10 MB. Send either multipart/form-data or JSON.

FieldDescription
fileThe file (multipart only)
contentText of a .md or .txt document (JSON; filename required)
content_base64Binary file in base64 (JSON; use up to about 3 MB)
urlPublic file URL that the server downloads (JSON; plans with web URL import only)
upload_idId from POST /documents/upload-url after you uploaded the file
filenameFile name with extension
descriptionOptional description
replace_existingDefault true: a file with the same name is replaced by the new version

In JSON, send exactly one of content, content_base64, url, upload_id.

{ "filename": "faq.md", "content": "# FAQ\n\n## Opening hours\n..." }

Large or local files

  1. POST /documents/upload-url with { "filename": "price-list.pdf" }. The response contains upload_id, upload_url and headers; the URL is valid for 2 hours and works once.
  2. Send the raw file with PUT to upload_url.
  3. POST /documents with { "upload_id": "...", "filename": "price-list.pdf" }.

Processing and status

Processing is asynchronous. The status moves from pending through processing to completed, or ends as failed with an error_message. A failed document stays in the list; delete it or upload it again. Poll GET /documents/{id} until completed.

Edit and replace

  • PATCH /documents/{id}/content sends only the change: edits (list of old_text and new_text, each old_text must occur exactly once, up to 100) and/or append (text, optional after_heading).
  • expected_hash (from GET .../content) protects against overwriting a newer version (409 CONFLICT).
  • Only UTF-8 .md and .txt documents can be edited (400 NOT_EDITABLE otherwise).
  • Every edit or replacement creates a new document_id; the old version keeps answering until the new one is completed.
  • A second change while the document is still processing returns 409 REPLACE_IN_PROGRESS.

Conversations#

Read the conversation history of the chatbot, including conversations created in the widget. These calls are read-only and do not use the message quota.

Endpoints

Method and pathDescriptionKey parametersMCP tool
GET /conversationsList conversationsSee belowlist_conversations
GET /conversations/{id}One conversation-get_conversation
GET /conversations/{id}/messagesMessages in chronological orderlimit (default 50, max 200), offsetget_conversation_messages

All three use the read limit of 120 requests per minute (see Rate limits). A conversation of another chatbot returns 404 NOT_FOUND.

List filters

ParameterDescription
limit, offsetPaging (default 20, max 100)
statusactive, completed or ticket_created
sourcewidget or api
from, toISO 8601 dates; filter on the start of the conversation
qualityConversations with at least one question of this kind: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified
qFull-text search in message text (2 to 200 characters)

Response

{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "uuid",
        "started_at": "2026-01-01T10:00:00Z",
        "last_activity_at": "2026-01-01T10:15:00Z",
        "message_count": 5,
        "status": "active",
        "source": "widget",
        "email": "visitor@example.com",
        "phone": null
      }
    ],
    "pagination": { "limit": 20, "offset": 0, "total": 42 }
  }
}

On plans with tickets, the detail of a conversation also contains tickets created in it. Messages have id, role (user or assistant), content and created_at.

Tip

To find questions the chatbot could not answer, use GET /analytics/top-queries?quality=not_answered (see Analytics) and open the related conversations through conversation_ids.

Analytics#

Aggregated statistics of the chatbot. Analytics is available on every plan, Free included. These calls do not use the message quota.

Endpoints

Method and pathDescriptionMCP tool
GET /analytics/summaryTotals for the periodget_analytics_summary
GET /analytics/timeseriesCounts per hour, day or weekget_analytics_timeseries
GET /analytics/top-queriesMost frequent questionsget_top_queries, list_knowledge_gaps

All three use the analytics limit of 60 requests per minute (see Rate limits).

Common parameters

ParameterDescription
periodtoday (default), week, month or quarter, evaluated in the time zone of the chatbot
from, toISO 8601 dates; they replace period; the range is at most 366 days
sourcewidget or api

Additional parameters

EndpointParameterDescription
timeseriesgranularityauto (default), hour, day or week; hour with quarter is refused
top-querieslimit, offsetPaging (default 20, max 100)
top-queriesqualityanswered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified

Summary response

{
  "period": "week",
  "total_queries": 7,
  "answered_queries": 5,
  "not_answered_queries": 1,
  "conversation_queries": 1,
  "off_topic_queries": 0,
  "ticket_created_queries": 0,
  "tool_call_queries": 0,
  "success_rate": 83.3,
  "widget_queries": 6,
  "api_queries": 1
}

success_rate is answered divided by answered plus not answered, in percent.

Unanswered questions

GET /analytics/top-queries?quality=not_answered&period=month returns the questions the chatbot could not answer, most frequent first. Each item has content, count, last_asked and up to 5 conversation_ids that you can open through conversations. Add the missing facts to the knowledge base and verify the result with chat.

Tickets#

Read support tickets, change their status and add internal notes. Tickets are available on the Evaluation, Support and Automate plans; Free returns 403 FORBIDDEN. Tickets cannot be created through the API: the chatbot creates them during a conversation.

Endpoints

Method and pathDescriptionKey parametersMCP tool
GET /ticketsList tickets, newest firstlimit (default 20, max 100), offset, status, conversation_id, from, tolist_tickets
GET /tickets/{id}One ticket-get_ticket
PATCH /tickets/{id}Change the statusstatus in the bodyupdate_ticket_status
GET /tickets/{id}/notesInternal notes, oldest first-list_ticket_notes
POST /tickets/{id}/notesAdd a note; returns 201content in the bodyadd_ticket_note

GET calls use the read limit (120 per minute), PATCH and POST the write limit (60 per minute); see Rate limits.

Values

ItemValue
Statusopen, in_progress, resolved, closed
NoteNon-empty text, up to 5000 characters

An invalid status returns 400 INVALID_REQUEST. A ticket of another chatbot returns 404 NOT_FOUND.

Ticket object

{
  "id": "uuid",
  "ticket_number": "TKT-000015",
  "conversation_id": "uuid",
  "email": "visitor@example.com",
  "phone": null,
  "summary": "The visitor asked to speak with a person.",
  "status": "open",
  "created_at": "2026-01-01T10:00:00Z",
  "updated_at": "2026-01-01T10:00:00Z"
}

Example

curl -X PATCH https://www.chatbotty.ai/api/v1/tickets/TICKET_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'

Webhook actions#

Manage the webhook actions of the chatbot: external APIs or automation webhooks (for example n8n) that the chatbot calls as tools while answering. Available on the Automate plan (10 webhooks and 10 tools per chatbot) and the Evaluation trial (5 webhooks and 5 tools per chatbot). Other plans get 403 FORBIDDEN; going over the limits returns 403 LIMIT_EXCEEDED. Calls do not use the message quota.

Endpoints

Method and pathDescriptionMCP tool
GET /webhooksList webhooks and the usage of your limitslist_webhook_actions
POST /webhooksCreate a webhook, optionally with tools; returns 201create_webhook_action
GET /webhooks/{id}One webhook with its toolsget_webhook_action
PATCH /webhooks/{id}Change a webhookupdate_webhook_action
DELETE /webhooks/{id}Delete a webhook with its toolsdelete_webhook_action
POST /webhooks/{id}/toolsAdd a tool; returns 201add_webhook_tool
PATCH /webhooks/{id}/tools/{toolId}Change a toolupdate_webhook_tool
DELETE /webhooks/{id}/tools/{toolId}Delete a tooldelete_webhook_tool
POST /webhooks/{id}/testCall the webhook like the chatbot doestest_webhook_action

Reads use the read limit (120 per minute), changes the write limit (60), and the test has its own limit of 20 per minute; see Rate limits. The MCP tool get_webhook_guide returns a short guide for AI assistants.

Webhook fields

FieldDescription
nameRequired, up to 100 characters
webhook_urlRequired, public HTTPS address
http_methodPOST (default) or GET
send_metadataDefault true: the call also carries tool_name, args and metadata (chatbot_id, conversation_id, timestamp); false sends only the arguments
timeout_ms1000 to 30000, default 10000
headersUp to 20 custom headers
secret_queryUp to 10 secret query parameters, for example an API key
toolsTools the chatbot may call (see below)

Tool fields

FieldDescription
nameLowercase letters, digits and underscores, starts with a letter, up to 64 characters, unique per chatbot; create_support_ticket is reserved
descriptionUp to 500 characters; tells the chatbot when to use the tool
parametersUp to 10 items with name, type (string, number, boolean), description (up to 200 characters), required

Rules

  • Values of headers and secret_query are never returned, only their names. A key found in webhook_url is moved to secret_query automatically and reported in warnings.
  • Changing the endpoint of a webhook requires sending all stored headers and secret_query keys again, so secrets cannot move to another server unnoticed.
  • The chatbot makes one round of tool calls per answer. A response is cut at 10 KB, redirects are not followed and internal addresses are refused.

Test

POST /webhooks/{id}/test with an optional body { "tool_name": "get_weather", "arguments": { "q": "Prague" } } returns ok, status, response_time_ms, body_preview (first 2 KB), truncated and warnings. After a test, ask the chatbot a matching question through chat and check tools_executed.

Errors#

Failed REST calls return a non-2xx HTTP status and this envelope:

{
  "success": false,
  "error": { "code": "INVALID_REQUEST", "message": "message is required and cannot be empty", "details": {} },
  "timestamp": "2026-01-01T10:00:00.000Z"
}

details is present only for some errors. Handle errors by code; messages may change.

Error codes

CodeHTTPMeaning
UNAUTHORIZED401Missing, invalid or deactivated API key
QUOTA_EXCEEDED403Monthly message quota used up (details.quota_info)
FORBIDDEN403The feature is not in your plan
LIMIT_EXCEEDED403Plan limit for webhooks or tools reached (details.resource, used, max)
INVALID_REQUEST400Invalid body or parameters
INVALID_URL400Webhook URL is invalid, not HTTPS or not public
INVALID_FILE400The file is missing from the upload
FILE_TOO_LARGE400File over 10 MB
UNSUPPORTED_FILE_TYPE400Only .pdf, .docx, .txt, .md are accepted
CONVERSATION_NOT_FOUND400conversation_id does not exist or belongs to another chatbot
EDIT_FAILED400Text to replace not found, or found more than once
NOT_EDITABLE400Only UTF-8 .md and .txt documents can be edited
NOT_FOUND404Document, ticket, webhook, tool or upload not found, or inactive chatbot
DUPLICATE_FILENAME409A document with this name exists (details.existing_document_id)
DUPLICATE_CONTENT409The same content is already indexed
REPLACE_IN_PROGRESS409The document is being replaced or processed; wait until it is completed
CONFLICT409Tool name already exists, or the document changed since you read it
STORAGE_LIMIT_EXCEEDED413Storage limit of the chatbot exceeded
RATE_LIMITED429Too many requests; see Rate limits
GONE_USE_V1410The old /api/chat endpoint was removed; use /api/v1/chat
INTERNAL_ERROR500Unexpected server error

MCP errors

The MCP endpoint answers with JSON-RPC errors: 401 for a missing or invalid token, 429 for too many requests and 403 when the plan has no MCP. When a tool fails, the result is marked as an error and contains the API code, for example Chatbotty API error [NOT_FOUND] (HTTP 404). See MCP connector.

Support

If an error persists, write to support@chatbotty.ai and include the code, the time and the endpoint.

MCP connector#

The MCP connector lets an AI assistant such as Claude, n8n or Cursor work with your chatbot: chat with it, manage its knowledge base, set up webhook actions and read conversations, analytics and tickets. One connector belongs to one chatbot; to use another chatbot, add another connector.

Connection

ItemValue
Server URLhttps://www.chatbotty.ai/api/mcp
TransportStreamable HTTP over POST
PlansAll plans; checked on every request
Limit300 requests per minute per key (see Rate limits)

Sign-in or key

MethodUsed byHow
Sign-in (OAuth)claude.ai, Claude Desktop, Claude mobile, Claude CodeThe client opens a Chatbotty page; you sign in, choose the chatbot and click Allow. A key is created automatically
API keyn8n, Cursor, VS Code, other clientsSend the header Authorization: Bearer YOUR_API_KEY (Authentication)

A key created by signing in is labelled MCP connector in API & MCP. Delete it there to disconnect the assistant. Tickets and webhook tools appear only if your plan includes them. Setup steps are in MCP clients.

Tools

AreaTools
Chatbot and chatget_chatbot_info, send_message
Documentslist_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document
Knowledge gapslist_knowledge_gaps
Conversationslist_conversations, get_conversation, get_conversation_messages
Analyticsget_analytics_summary, get_analytics_timeseries, get_top_queries
Tickets (plans with tickets)list_tickets, get_ticket, update_ticket_status, list_ticket_notes, add_ticket_note
Webhook actions (plans with webhook actions)get_webhook_guide, list_webhook_actions, get_webhook_action, create_webhook_action, update_webhook_action, test_webhook_action, delete_webhook_action, add_webhook_tool, update_webhook_tool, delete_webhook_tool

Every tool works like the matching REST endpoint described in the sections above and has the same limits and errors.

Good to know

  • send_message talks to the chatbot like a visitor and uses the monthly message quota. test_webhook_action does not.
  • list_knowledge_gaps lists questions the chatbot could not answer and needs a period; use it to find what to add to the knowledge base.
  • A client may cache tool descriptions. If tools look outdated, remove the connector and add it again.

MCP clients#

How to connect common clients to https://www.chatbotty.ai/api/mcp. For clients that send a key, create it first as described in Authentication. Background: MCP connector.

Claude (claude.ai, Claude Desktop, mobile)

  1. Open Settings, then Connectors, then add a custom connector.
  2. Paste the server URL and click Connect.
  3. Sign in to Chatbotty, choose the chatbot and click Allow.

No API key is needed. The connector then also works in the Claude mobile app.

Claude Code

Sign in through the browser:

claude mcp add --transport http chatbotty https://www.chatbotty.ai/api/mcp

Or use an API key:

claude mcp add --transport http chatbotty https://www.chatbotty.ai/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

When the sign-in page warns that the app runs on your own computer, allow access only if you started the connection yourself.

n8n

  1. Add the MCP Client Tool node.
  2. Endpoint: the server URL.
  3. Server Transport: HTTP Streamable.
  4. Authentication: Bearer Auth with your API key.

Cursor, VS Code and other clients

Add a remote MCP server with the server URL and the header Authorization: Bearer YOUR_API_KEY. In Cursor, for example:

{
  "mcpServers": {
    "chatbotty": {
      "url": "https://www.chatbotty.ai/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Troubleshooting

ProblemCheck
401The key is wrong, deactivated or deleted
Tickets or webhook tools missingYour plan does not include them
Manual client gets 406The client must send Accept: application/json, text/event-stream

Examples#

Copy-paste examples for the most common tasks. Replace YOUR_API_KEY with a key from API & MCP and https://www.chatbotty.ai with the base URL. See Authentication.

Check the chatbot and quota

curl https://www.chatbotty.ai/api/v1/chatbot \
  -H "Authorization: Bearer YOUR_API_KEY"

Ask a question and continue the conversation

curl -X POST https://www.chatbotty.ai/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your opening hours?"}'

Take conversation_id from the response and send it with the next message:

curl -X POST https://www.chatbotty.ai/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "And on Sunday?", "conversation_id": "CONVERSATION_ID"}'

Upload a document

curl -X POST https://www.chatbotty.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./faq.md"

Then check the status until it is completed:

curl https://www.chatbotty.ai/api/v1/documents/DOCUMENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Find unanswered questions

curl "https://www.chatbotty.ai/api/v1/analytics/top-queries?quality=not_answered&period=month" \
  -H "Authorization: Bearer YOUR_API_KEY"

List conversations that contain a word

curl "https://www.chatbotty.ai/api/v1/conversations?q=refund&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Handle errors

{ "success": false, "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Maximum 60 requests per minute per API key." }, "timestamp": "2026-01-01T10:00:00.000Z" }

Branch on error.code and see Errors. For limits, see Rate limits. Questions: support@chatbotty.ai.