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
| Item | Value |
|---|---|
| REST base URL | https://www.chatbotty.ai/api/v1 |
| MCP server URL | https://www.chatbotty.ai/api/mcp |
| Format | JSON over HTTPS |
| Authentication | Authorization: Bearer YOUR_API_KEY |
| Scope of a key | One 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.
| Feature | Free | Evaluation | Support | Automate |
|---|---|---|---|---|
| Chat, documents, conversations, analytics | Yes | Yes | Yes | Yes |
| Tickets | No | Yes | Yes | Yes |
| Webhook actions | No | Yes | No | Yes |
| Document import from a web URL | No | Yes | Yes | Yes |
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 /chator the MCP toolsend_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 withGET /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
| Item | Value |
|---|---|
| Format | A random 64-character hexadecimal string |
| Scope | One chatbot per key |
| Limit | Up to 50 keys per chatbot (inactive keys count too) |
| Storage | Only 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
- Open API & MCP in the sidebar.
- On the card of your chatbot, click Create new API key, enter a name (for example "Production app") and click Create.
- 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.
| Action | Effect |
|---|---|
| Deactivate | The key stops working at once; Activate turns it back on |
| Delete | The 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
| Situation | Response |
|---|---|
| Header missing or malformed | 401 UNAUTHORIZED "Missing or invalid Authorization header" |
| Unknown or deactivated key | 401 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
| Class | Endpoints | Limit per minute |
|---|---|---|
| Chat | POST /chat | 60 |
| Read | All other GET endpoints except analytics (including GET /chatbot) | 120 |
| Write | POST, PATCH, DELETE endpoints | 60 |
| Analytics | GET /analytics/summary, /analytics/timeseries, /analytics/top-queries | 60 |
| Webhook test | POST /webhooks/{id}/test | 20 |
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
| Item | Value |
|---|---|
| Method and path | GET https://www.chatbotty.ai/api/v1/chatbot |
| Parameters | None |
| Rate limit | Read class (see Rate limits) |
| Quota | Not used |
| MCP tool | get_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
planandmessage_quotabelong to the account owner; the quota is shared by all chatbots of the account.featuresshows which plan-dependent features this key can use.handoff_contactis the contact the chatbot gives when it does not know the answer (read-only here;nullwhen not set).last_updated_atis 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
| Item | Value |
|---|---|
| Method and path | POST https://www.chatbotty.ai/api/v1/chat |
| Rate limit | Chat class: 60 per minute |
| Quota | One message per call; over the quota the call returns 403 QUOTA_EXCEEDED |
| MCP tool | send_message |
Request body
| Field | Required | Description |
|---|---|---|
message | Yes | The visitor's question (non-empty text) |
conversation_id | No | Continues an existing conversation; omit it to start a new one |
options | No | Optional 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 path | Description | Key parameters | MCP tool |
|---|---|---|---|
GET /documents | List documents | limit (default 20, max 100), offset, status | list_documents |
POST /documents | Upload a document; returns 202 | See below | upload_document |
POST /documents/upload-url | Get a signed URL for a large or local file | filename | create_upload_url |
GET /documents/{id} | Status and details of one document | - | get_document |
DELETE /documents/{id} | Delete a document | - | delete_document |
GET /documents/{id}/content | Read the text, paged | offset, limit (default 20000, max 50000) | read_document |
PATCH /documents/{id}/content | Edit a .md or .txt document | edits, append, expected_hash | edit_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.
| Field | Description |
|---|---|
file | The file (multipart only) |
content | Text of a .md or .txt document (JSON; filename required) |
content_base64 | Binary file in base64 (JSON; use up to about 3 MB) |
url | Public file URL that the server downloads (JSON; plans with web URL import only) |
upload_id | Id from POST /documents/upload-url after you uploaded the file |
filename | File name with extension |
description | Optional description |
replace_existing | Default 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
POST /documents/upload-urlwith{ "filename": "price-list.pdf" }. The response containsupload_id,upload_urland headers; the URL is valid for 2 hours and works once.- Send the raw file with
PUTtoupload_url. POST /documentswith{ "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}/contentsends only the change:edits(list ofold_textandnew_text, eachold_textmust occur exactly once, up to 100) and/orappend(text, optionalafter_heading).expected_hash(fromGET .../content) protects against overwriting a newer version (409 CONFLICT).- Only UTF-8
.mdand.txtdocuments can be edited (400 NOT_EDITABLEotherwise). - Every edit or replacement creates a new
document_id; the old version keeps answering until the new one iscompleted. - 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 path | Description | Key parameters | MCP tool |
|---|---|---|---|
GET /conversations | List conversations | See below | list_conversations |
GET /conversations/{id} | One conversation | - | get_conversation |
GET /conversations/{id}/messages | Messages in chronological order | limit (default 50, max 200), offset | get_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
| Parameter | Description |
|---|---|
limit, offset | Paging (default 20, max 100) |
status | active, completed or ticket_created |
source | widget or api |
from, to | ISO 8601 dates; filter on the start of the conversation |
quality | Conversations with at least one question of this kind: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified |
q | Full-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 path | Description | MCP tool |
|---|---|---|
GET /analytics/summary | Totals for the period | get_analytics_summary |
GET /analytics/timeseries | Counts per hour, day or week | get_analytics_timeseries |
GET /analytics/top-queries | Most frequent questions | get_top_queries, list_knowledge_gaps |
All three use the analytics limit of 60 requests per minute (see Rate limits).
Common parameters
| Parameter | Description |
|---|---|
period | today (default), week, month or quarter, evaluated in the time zone of the chatbot |
from, to | ISO 8601 dates; they replace period; the range is at most 366 days |
source | widget or api |
Additional parameters
| Endpoint | Parameter | Description |
|---|---|---|
timeseries | granularity | auto (default), hour, day or week; hour with quarter is refused |
top-queries | limit, offset | Paging (default 20, max 100) |
top-queries | quality | answered, 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 path | Description | Key parameters | MCP tool |
|---|---|---|---|
GET /tickets | List tickets, newest first | limit (default 20, max 100), offset, status, conversation_id, from, to | list_tickets |
GET /tickets/{id} | One ticket | - | get_ticket |
PATCH /tickets/{id} | Change the status | status in the body | update_ticket_status |
GET /tickets/{id}/notes | Internal notes, oldest first | - | list_ticket_notes |
POST /tickets/{id}/notes | Add a note; returns 201 | content in the body | add_ticket_note |
GET calls use the read limit (120 per minute), PATCH and POST the write limit (60 per minute); see Rate limits.
Values
| Item | Value |
|---|---|
| Status | open, in_progress, resolved, closed |
| Note | Non-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 path | Description | MCP tool |
|---|---|---|
GET /webhooks | List webhooks and the usage of your limits | list_webhook_actions |
POST /webhooks | Create a webhook, optionally with tools; returns 201 | create_webhook_action |
GET /webhooks/{id} | One webhook with its tools | get_webhook_action |
PATCH /webhooks/{id} | Change a webhook | update_webhook_action |
DELETE /webhooks/{id} | Delete a webhook with its tools | delete_webhook_action |
POST /webhooks/{id}/tools | Add a tool; returns 201 | add_webhook_tool |
PATCH /webhooks/{id}/tools/{toolId} | Change a tool | update_webhook_tool |
DELETE /webhooks/{id}/tools/{toolId} | Delete a tool | delete_webhook_tool |
POST /webhooks/{id}/test | Call the webhook like the chatbot does | test_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
| Field | Description |
|---|---|
name | Required, up to 100 characters |
webhook_url | Required, public HTTPS address |
http_method | POST (default) or GET |
send_metadata | Default true: the call also carries tool_name, args and metadata (chatbot_id, conversation_id, timestamp); false sends only the arguments |
timeout_ms | 1000 to 30000, default 10000 |
headers | Up to 20 custom headers |
secret_query | Up to 10 secret query parameters, for example an API key |
tools | Tools the chatbot may call (see below) |
Tool fields
| Field | Description |
|---|---|
name | Lowercase letters, digits and underscores, starts with a letter, up to 64 characters, unique per chatbot; create_support_ticket is reserved |
description | Up to 500 characters; tells the chatbot when to use the tool |
parameters | Up to 10 items with name, type (string, number, boolean), description (up to 200 characters), required |
Rules
- Values of
headersandsecret_queryare never returned, only their names. A key found inwebhook_urlis moved tosecret_queryautomatically and reported inwarnings. - Changing the endpoint of a webhook requires sending all stored
headersandsecret_querykeys 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
| Code | HTTP | Meaning |
|---|---|---|
UNAUTHORIZED | 401 | Missing, invalid or deactivated API key |
QUOTA_EXCEEDED | 403 | Monthly message quota used up (details.quota_info) |
FORBIDDEN | 403 | The feature is not in your plan |
LIMIT_EXCEEDED | 403 | Plan limit for webhooks or tools reached (details.resource, used, max) |
INVALID_REQUEST | 400 | Invalid body or parameters |
INVALID_URL | 400 | Webhook URL is invalid, not HTTPS or not public |
INVALID_FILE | 400 | The file is missing from the upload |
FILE_TOO_LARGE | 400 | File over 10 MB |
UNSUPPORTED_FILE_TYPE | 400 | Only .pdf, .docx, .txt, .md are accepted |
CONVERSATION_NOT_FOUND | 400 | conversation_id does not exist or belongs to another chatbot |
EDIT_FAILED | 400 | Text to replace not found, or found more than once |
NOT_EDITABLE | 400 | Only UTF-8 .md and .txt documents can be edited |
NOT_FOUND | 404 | Document, ticket, webhook, tool or upload not found, or inactive chatbot |
DUPLICATE_FILENAME | 409 | A document with this name exists (details.existing_document_id) |
DUPLICATE_CONTENT | 409 | The same content is already indexed |
REPLACE_IN_PROGRESS | 409 | The document is being replaced or processed; wait until it is completed |
CONFLICT | 409 | Tool name already exists, or the document changed since you read it |
STORAGE_LIMIT_EXCEEDED | 413 | Storage limit of the chatbot exceeded |
RATE_LIMITED | 429 | Too many requests; see Rate limits |
GONE_USE_V1 | 410 | The old /api/chat endpoint was removed; use /api/v1/chat |
INTERNAL_ERROR | 500 | Unexpected 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
| Item | Value |
|---|---|
| Server URL | https://www.chatbotty.ai/api/mcp |
| Transport | Streamable HTTP over POST |
| Plans | All plans; checked on every request |
| Limit | 300 requests per minute per key (see Rate limits) |
Sign-in or key
| Method | Used by | How |
|---|---|---|
| Sign-in (OAuth) | claude.ai, Claude Desktop, Claude mobile, Claude Code | The client opens a Chatbotty page; you sign in, choose the chatbot and click Allow. A key is created automatically |
| API key | n8n, Cursor, VS Code, other clients | Send 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
| Area | Tools |
|---|---|
| Chatbot and chat | get_chatbot_info, send_message |
| Documents | list_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document |
| Knowledge gaps | list_knowledge_gaps |
| Conversations | list_conversations, get_conversation, get_conversation_messages |
| Analytics | get_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_messagetalks to the chatbot like a visitor and uses the monthly message quota.test_webhook_actiondoes not.list_knowledge_gapslists 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)
- Open Settings, then Connectors, then add a custom connector.
- Paste the server URL and click Connect.
- 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
- Add the MCP Client Tool node.
- Endpoint: the server URL.
- Server Transport: HTTP Streamable.
- 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
| Problem | Check |
|---|---|
401 | The key is wrong, deactivated or deleted |
| Tickets or webhook tools missing | Your plan does not include them |
Manual client gets 406 | The 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.