REST API

The ChatReact REST API v1 gives you programmatic access to everything you can do in the dashboard: chatbots, knowledge base and crawling, FAQs, chat review and the Improvement Agent, leads, contact forms, live chat, company and team, the Email Assistant, analytics and notifications. Only browser-bound actions (payments, mailbox OAuth, passkeys, account deletion and API key management) stay in the dashboard.

Prefer talking to an AI assistant? The same capabilities are available as MCP tools — see MCP Server Integration. The interactive API Explorer with request and response schemas lives at /api-reference, where you can also download the OpenAPI 3.0 specification.

Authentication

Go to Dashboard → Company → API tab and click Create API Key
Choose a name and the permission scopes the key needs (see below)
Copy the key — it starts with cr_ and is shown only once

Send the key with every request:

curl https://www.chatreact.ai/api/v1/chatbots \
  -H "Authorization: Bearer cr_your_api_key"

An X-API-Key: cr_your_api_key header is accepted as well. API keys belong to one company and execute with the permissions of the company owner; plan limits and feature gates apply exactly as in the dashboard.

API access is available on paid plans — see the Pricing page. Keys can be revoked at any time from the dashboard.

Scopes

Each key carries one or more scopes. An endpoint returns 403 when the key lacks the required scope.

Scope	Grants
`chatbots:read` / `chatbots:write`	Chatbot configuration: persona, languages, widget, behavior, restrictions, core instructions, embed code, learning phase, chatbot templates, FAQ widget settings
`knowledge:read` / `knowledge:write`	Knowledge base: documents, website crawling, crawled pages
`faqs:read` / `faqs:write`	FAQs, FAQ categories, suggestions, translations
`chats:read` / `chats:write`	Chat history, chat ratings, confidence categories, live chat (agent actions need `chats:write`)
`leads:read` / `leads:write`	Leads, lead categories, lead capture settings, export
`forms:read` / `forms:write`	Contact forms and submissions
`analytics:read`	Statistics, activity series, funnels, confidence status
`company:read` / `company:write`	Company profile and settings, team members, invitations
`email:read` / `email:write`	Email Assistant connections, categories, contacts, activity
`blog:read` / `blog:write`	Platform blog content (ChatReact internal)
any valid key	`/v1/me`, account usage, your notifications

Conventions

Base URL: https://www.chatreact.ai/api/v1, JSON in and out (Content-Type: application/json).
Responses: { "success": true, "data": … }; lists add "pagination": { "total", "page", "pageSize", "totalPages" }. Use page and pageSize (max 100) on list endpoints; some endpoints offer cursor pagination (cursor / nextCursor).
Errors: { "success": false, "error": "message", "code": "BAD_REQUEST" } with optional details for validation errors. Status codes: 400 invalid input, 401 missing or invalid key, 403 missing scope, plan feature not included or insufficient role, 404 resource not found (also for resources of other companies), 409 conflict, 429 rate limit exceeded.
Partial updates: PATCH endpoints change only the fields you send; unknown fields are rejected.
Rate limit: 30 requests per minute per IP address.
Long-running operations (crawls, AI generation, translations) return quickly with a job or result you can poll; they consume the token and crawl budget of your plan.

Endpoints

Chatbots

Method	Path	Description	Scope
`GET`	`/api/v1/chatbots`	List chatbots	`chatbots:read`
`POST`	`/api/v1/chatbots`	Create chatbot	`chatbots:write`
`GET`	`/api/v1/chatbots/{id}`	Get chatbot	`chatbots:read`
`PATCH`	`/api/v1/chatbots/{id}`	Update chatbot	`chatbots:write`
`DELETE`	`/api/v1/chatbots/{id}`	Delete chatbot	`chatbots:write`
`GET`	`/api/v1/chatbots/{id}/personality`	Get chatbot personality	`chatbots:read`
`PATCH`	`/api/v1/chatbots/{id}/personality`	Update chatbot personality	`chatbots:write`
`GET`	`/api/v1/chatbots/{id}/widget`	Get widget settings	`chatbots:read`
`PATCH`	`/api/v1/chatbots/{id}/widget`	Update widget settings	`chatbots:write`
`GET`	`/api/v1/chatbots/{id}/widget/translations`	Get widget translations	`chatbots:read`
`PUT`	`/api/v1/chatbots/{id}/widget/translations`	Replace widget translations	`chatbots:write`
`GET`	`/api/v1/chatbots/{id}/embed`	Get embed code	`chatbots:read`
`POST`	`/api/v1/chatbots/{id}/embed/confirm`	Confirm embed	`chatbots:write`
`GET`	`/api/v1/chatbots/{id}/learning-phase`	Get learning-phase settings	`chatbots:read`
`PATCH`	`/api/v1/chatbots/{id}/learning-phase`	Update learning-phase settings	`chatbots:write`
`POST`	`/api/v1/chatbots/{id}/learning-phase/end`	End learning phase	`chatbots:write`
`GET`	`/api/v1/chatbots/{id}/instructions`	List core instructions	`chatbots:read`
`POST`	`/api/v1/chatbots/{id}/instructions`	Add core instruction	`chatbots:write`
`PUT`	`/api/v1/chatbots/{id}/instructions/reorder`	Reorder core instructions	`chatbots:write`
`POST`	`/api/v1/chatbots/{id}/instructions/improve`	Improve instructions with AI	`chatbots:write`
`GET`	`/api/v1/instructions/{id}`	Get core instruction	`chatbots:read`
`PATCH`	`/api/v1/instructions/{id}`	Update core instruction	`chatbots:write`
`DELETE`	`/api/v1/instructions/{id}`	Delete core instruction	`chatbots:write`
`GET`	`/api/v1/chatbot-templates`	List chatbot templates	`chatbots:read`

Knowledge base

Method	Path	Description	Scope
`GET`	`/api/v1/chatbots/{id}/knowledge`	Knowledge base overview	`knowledge:read`
`GET`	`/api/v1/chatbots/{id}/documents`	List documents for chatbot	`knowledge:read`
`POST`	`/api/v1/chatbots/{id}/documents`	Upload document	`knowledge:write`
`POST`	`/api/v1/chatbots/{id}/documents/presign`	Presign document upload	`knowledge:write`
`GET`	`/api/v1/documents/{id}`	Get document	`knowledge:read`
`DELETE`	`/api/v1/documents/{id}`	Delete document	`knowledge:write`
`POST`	`/api/v1/documents/{id}/confirm`	Confirm presigned upload	`knowledge:write`
`GET`	`/api/v1/chatbots/{id}/crawl/limits`	Crawl limits	`knowledge:read`
`POST`	`/api/v1/chatbots/{id}/crawl/preview`	Preview scan website	`knowledge:write`
`GET`	`/api/v1/chatbots/{id}/crawl`	List crawl jobs	`knowledge:read`
`POST`	`/api/v1/chatbots/{id}/crawl`	Start crawl	`knowledge:write`
`GET`	`/api/v1/crawl-jobs/{jobId}`	Get crawl job	`knowledge:read`
`POST`	`/api/v1/crawl-jobs/{jobId}/cancel`	Cancel crawl job	`knowledge:write`
`GET`	`/api/v1/chatbots/{id}/pages`	List crawled pages	`knowledge:read`
`POST`	`/api/v1/chatbots/{id}/pages`	Add single URL	`knowledge:write`
`POST`	`/api/v1/chatbots/{id}/pages/bulk-delete`	Bulk-delete crawled pages	`knowledge:write`
`GET`	`/api/v1/pages/{id}`	Get crawled page	`knowledge:read`
`DELETE`	`/api/v1/pages/{id}`	Delete crawled page	`knowledge:write`
`POST`	`/api/v1/pages/{id}/recrawl`	Re-crawl page	`knowledge:write`
`GET`	`/api/v1/chatbots/{id}/websites`	List crawled websites	`knowledge:read`
`DELETE`	`/api/v1/chatbots/{id}/websites/{domain}`	Delete website	`knowledge:write`
`POST`	`/api/v1/chatbots/{id}/websites/{domain}/recrawl`	Re-crawl website	`knowledge:write`
`POST`	`/api/v1/chatbots/{id}/websites/{domain}/recrawl/cancel`	Cancel website re-crawl	`knowledge:write`

FAQs

Method	Path	Description	Scope
`GET`	`/api/v1/chatbots/{id}/faqs`	List FAQs for chatbot	`faqs:read`
`POST`	`/api/v1/chatbots/{id}/faqs`	Create FAQ	`faqs:write`
`POST`	`/api/v1/chatbots/{id}/faqs/bulk`	Bulk import FAQs	`faqs:write`
`POST`	`/api/v1/chatbots/{id}/faqs/reorder`	Reorder FAQs	`faqs:write`
`GET`	`/api/v1/chatbots/{id}/faqs/embed`	Get FAQ widget embed code	`chatbots:read`
`POST`	`/api/v1/chatbots/{id}/faqs/purge-cache`	Purge remote FAQ caches	`faqs:write`
`GET`	`/api/v1/faqs/{id}`	Get FAQ	`faqs:read`
`PATCH`	`/api/v1/faqs/{id}`	Update FAQ	`faqs:write`
`DELETE`	`/api/v1/faqs/{id}`	Delete FAQ	`faqs:write`
`PUT`	`/api/v1/faqs/{id}/translations`	Update FAQ translations	`faqs:write`
`POST`	`/api/v1/faqs/{id}/translate`	AI-translate FAQ	`faqs:write`
`GET`	`/api/v1/chatbots/{id}/faq-suggestions`	List FAQ suggestions	`faqs:read`
`POST`	`/api/v1/chatbots/{id}/faq-suggestions/generate`	Generate FAQ suggestions from knowledge base	`faqs:write`
`GET`	`/api/v1/faq-suggestions/{id}`	Get FAQ suggestion	`faqs:read`
`POST`	`/api/v1/faq-suggestions/{id}/approve`	Approve FAQ suggestion	`faqs:write`
`POST`	`/api/v1/faq-suggestions/{id}/reject`	Reject FAQ suggestion	`faqs:write`
`GET`	`/api/v1/chatbots/{id}/faq-categories`	List FAQ categories	`faqs:read`
`POST`	`/api/v1/chatbots/{id}/faq-categories`	Create FAQ category	`faqs:write`
`POST`	`/api/v1/chatbots/{id}/faq-categories/reorder`	Reorder FAQ categories	`faqs:write`
`GET`	`/api/v1/faq-categories/{id}`	Get FAQ category	`faqs:read`
`PATCH`	`/api/v1/faq-categories/{id}`	Update FAQ category	`faqs:write`
`DELETE`	`/api/v1/faq-categories/{id}`	Delete FAQ category	`faqs:write`
`PUT`	`/api/v1/faq-categories/{id}/translations`	Update FAQ category translations	`faqs:write`
`GET`	`/api/v1/chatbots/{id}/faq-widget-settings`	Get FAQ widget settings	`chatbots:read`
`PATCH`	`/api/v1/chatbots/{id}/faq-widget-settings`	Update FAQ widget settings	`chatbots:write`

Chats, feedback & Improvement Agent

Method	Path	Description	Scope
`GET`	`/api/v1/chats`	List chat sessions	`chats:read`
`GET`	`/api/v1/chats/{sessionId}`	Get chat session	`chats:read`
`PATCH`	`/api/v1/chats/{sessionId}`	Set chat confidence category	`chats:write`
`POST`	`/api/v1/chats/{sessionId}/feedback`	Rate chat (Good / Needs Work)	`chats:write`
`POST`	`/api/v1/chats/{sessionId}/feedback/dismiss`	Dismiss chat review	`chats:write`
`POST`	`/api/v1/chats/{sessionId}/improve`	Start Improvement Agent for chat	`chatbots:write`
`GET`	`/api/v1/chatbots/{id}/feedback`	List chat reviews of a chatbot	`chats:read`
`GET`	`/api/v1/chatbots/{id}/feedback/stats`	Chat review stat cards	`chats:read`
`GET`	`/api/v1/feedback/{id}`	Get chat review	`chats:read`
`PATCH`	`/api/v1/feedback/{id}`	Override review severity	`chats:write`
`POST`	`/api/v1/feedback/{id}/improvement-session`	Start Improvement Agent for review	`chatbots:write`
`GET`	`/api/v1/chatbots/{id}/confidence`	Get confidence status	`analytics:read`
`GET`	`/api/v1/chatbots/{id}/confidence-categories`	List confidence categories	`chats:read`
`POST`	`/api/v1/chatbots/{id}/confidence-categories`	Create confidence category	`chatbots:write`
`PATCH`	`/api/v1/confidence-categories/{id}`	Update confidence category	`chatbots:write`
`DELETE`	`/api/v1/confidence-categories/{id}`	Delete confidence category	`chatbots:write`
`POST`	`/api/v1/confidence-categories/{id}/merge`	Merge confidence categories	`chatbots:write`
`GET`	`/api/v1/chatbots/{id}/improvement-sessions`	List improvement sessions	`chatbots:read`
`GET`	`/api/v1/improvement-sessions/{id}`	Get improvement session	`chatbots:read`
`POST`	`/api/v1/improvement-sessions/{id}/messages`	Send message to Improvement Agent	`chatbots:write`
`POST`	`/api/v1/improvement-sessions/{id}/complete`	Complete improvement session	`chatbots:write`
`POST`	`/api/v1/improvement-sessions/{id}/reset`	Reset improvement session	`chatbots:write`
`POST`	`/api/v1/improvement-proposals/{id}/apply`	Apply improvement proposal	`chatbots:write`
`POST`	`/api/v1/improvement-proposals/{id}/reject`	Reject improvement proposal	`chatbots:write`
`POST`	`/api/v1/improvement-proposals/{id}/simulations`	Simulate improvement proposal	`chatbots:write`
`POST`	`/api/v1/improvement-simulations/{id}/assessment`	Rate simulation result	`chatbots:write`

Leads

Method	Path	Description	Scope
`GET`	`/api/v1/leads`	List leads	`leads:read`
`POST`	`/api/v1/leads`	Create lead	`leads:write`
`GET`	`/api/v1/leads/{id}`	Get lead	`leads:read`
`PATCH`	`/api/v1/leads/{id}`	Update lead	`leads:write`
`DELETE`	`/api/v1/leads/{id}`	Delete lead	`leads:write`
`POST`	`/api/v1/leads/{id}/assign`	Assign lead	`leads:write`
`POST`	`/api/v1/leads/bulk-status`	Bulk update lead status	`leads:write`
`GET`	`/api/v1/leads/stats`	Lead statistics	`leads:read`
`GET`	`/api/v1/leads/export`	Export leads	`leads:read`
`GET`	`/api/v1/chatbots/{id}/lead-config`	Get lead capture configuration	`leads:read`
`PUT`	`/api/v1/chatbots/{id}/lead-config`	Update lead capture configuration	`leads:write`
`GET`	`/api/v1/chatbots/{id}/lead-categories`	List lead categories	`leads:read`
`POST`	`/api/v1/chatbots/{id}/lead-categories`	Create lead category	`leads:write`
`GET`	`/api/v1/lead-categories/{id}`	Get lead category	`leads:read`
`PATCH`	`/api/v1/lead-categories/{id}`	Update lead category	`leads:write`
`DELETE`	`/api/v1/lead-categories/{id}`	Delete lead category	`leads:write`
`PUT`	`/api/v1/lead-categories/{id}/users/{userId}`	Assign member to lead category	`leads:write`
`DELETE`	`/api/v1/lead-categories/{id}/users/{userId}`	Remove member from lead category	`leads:write`

Contact forms

Method	Path	Description	Scope
`GET`	`/api/v1/chatbots/{id}/forms`	List contact forms	`forms:read`
`POST`	`/api/v1/chatbots/{id}/forms`	Create contact form	`forms:write`
`GET`	`/api/v1/forms/{id}`	Get contact form	`forms:read`
`PATCH`	`/api/v1/forms/{id}`	Update contact form	`forms:write`
`DELETE`	`/api/v1/forms/{id}`	Delete contact form	`forms:write`
`GET`	`/api/v1/forms/{id}/submissions`	List form submissions	`forms:read`
`GET`	`/api/v1/forms/{id}/stats`	Form submission statistics	`forms:read`
`GET`	`/api/v1/submissions/{id}`	Get form submission	`forms:read`
`PATCH`	`/api/v1/submissions/{id}`	Review form submission	`forms:write`
`DELETE`	`/api/v1/submissions/{id}`	Delete form submission	`forms:write`

Live chat

Method	Path	Description	Scope
`GET`	`/api/v1/live-chat/availability`	Get own live chat availability	`chats:read`
`PUT`	`/api/v1/live-chat/availability`	Set own live chat availability	`chats:write`
`POST`	`/api/v1/live-chat/heartbeat`	Send presence heartbeat	`chats:write`
`GET`	`/api/v1/live-chat/agents`	List available live chat agents	`chats:read`
`GET`	`/api/v1/live-chat/sessions`	List live chat sessions	`chats:read`
`GET`	`/api/v1/live-chat/sessions/{sessionId}`	Get live chat session	`chats:read`
`POST`	`/api/v1/live-chat/sessions/{sessionId}/assign`	Take live chat (assign to key owner)	`chats:write`
`POST`	`/api/v1/live-chat/sessions/{sessionId}/messages`	Send message as agent	`chats:write`
`POST`	`/api/v1/live-chat/sessions/{sessionId}/close`	End live chat	`chats:write`

Analytics

Method	Path	Description	Scope
`GET`	`/api/v1/analytics`	Get analytics overview	`analytics:read`
`GET`	`/api/v1/analytics/activity`	Get chat activity series	`analytics:read`
`GET`	`/api/v1/analytics/chatbots`	List per-chatbot performance stats	`analytics:read`
`GET`	`/api/v1/analytics/chatbots/{id}`	Get chatbot analytics	`analytics:read`
`GET`	`/api/v1/analytics/leads`	Get lead funnel	`analytics:read`
`GET`	`/api/v1/analytics/forms`	Get form submission stats	`analytics:read`
`GET`	`/api/v1/activity`	Get attention summary	`analytics:read`

Company & team

Method	Path	Description	Scope
`GET`	`/api/v1/company`	Get company	any key
`PATCH`	`/api/v1/company`	Update company	`company:write`
`GET`	`/api/v1/company/settings`	Get company settings	`company:read`
`PATCH`	`/api/v1/company/settings`	Update company settings	`company:write`
`DELETE`	`/api/v1/company/logo`	Remove company logo	`company:write`
`GET`	`/api/v1/company/members`	List team members	`company:read`
`PATCH`	`/api/v1/company/members/{userId}`	Change member role	`company:write`
`DELETE`	`/api/v1/company/members/{userId}`	Remove team member	`company:write`
`GET`	`/api/v1/company/invites`	List invitations	`company:read`
`POST`	`/api/v1/company/invites`	Invite team member	`company:write`
`DELETE`	`/api/v1/company/invites/{id}`	Cancel invitation	`company:write`
`POST`	`/api/v1/company/invites/{id}/resend`	Resend invitation	`company:write`

Email Assistant

Method	Path	Description	Scope
`GET`	`/api/v1/email/connections`	List mailbox connections	`email:read`
`GET`	`/api/v1/email/connections/{id}`	Get mailbox connection	`email:read`
`PATCH`	`/api/v1/email/connections/{id}`	Update mailbox connection	`email:write`
`DELETE`	`/api/v1/email/connections/{id}`	Disconnect mailbox	`email:write`
`GET`	`/api/v1/email/connections/{id}/categories`	List email categories	`email:read`
`POST`	`/api/v1/email/connections/{id}/categories`	Create email category	`email:write`
`GET`	`/api/v1/email/connections/{id}/activity`	List email activity log	`email:read`
`GET`	`/api/v1/email/categories/{id}`	Get email category	`email:read`
`PATCH`	`/api/v1/email/categories/{id}`	Update email category	`email:write`
`DELETE`	`/api/v1/email/categories/{id}`	Delete email category	`email:write`
`GET`	`/api/v1/email/contacts`	List email contacts	`email:read`
`GET`	`/api/v1/email/contacts/{id}`	Get email contact	`email:read`
`PATCH`	`/api/v1/email/contacts/{id}`	Update email contact	`email:write`
`DELETE`	`/api/v1/email/contacts/{id}`	Delete email contact	`email:write`

Account & notifications

Method	Path	Description	Scope
`GET`	`/api/v1/me`	Get key context (whoami)	any key
`GET`	`/api/v1/account/usage`	Get plan and usage	any key
`GET`	`/api/v1/notifications`	List notifications	any key
`DELETE`	`/api/v1/notifications`	Delete old read notifications	any key
`GET`	`/api/v1/notifications/unread-count`	Get unread notification count	any key
`POST`	`/api/v1/notifications/mark-all-read`	Mark all notifications as read	any key
`GET`	`/api/v1/notifications/{id}`	Get notification	any key
`PATCH`	`/api/v1/notifications/{id}`	Mark notification as read	any key

Blog (platform)

Method	Path	Description	Scope
`GET`	`/api/v1/blog`	List blog posts	any key
`POST`	`/api/v1/blog`	Create blog post	any key
`POST`	`/api/v1/blog/assets`	Upload blog asset	any key
`GET`	`/api/v1/blog/{id}`	Get blog post	any key
`PATCH`	`/api/v1/blog/{id}`	Update blog post	any key
`DELETE`	`/api/v1/blog/{id}`	Delete blog post	any key
`POST`	`/api/v1/blog/{id}/translations`	Queue blog translations	any key

Need help? Contact our support team →