The ChatWith API

What the ChatWith API is

The ChatWith API is a chatbot API for the website assistant you already trained on your content. It is one HTTPS endpoint where you send JSON-RPC 2.0 requests with a workspace API key — not a generic LLM API for building a bot from scratch.

There is no public REST API and no resource-specific routes. Every call is an HTTP POST with a JSON-RPC 2.0 body to the MCP endpoint, which for your workspace is shown in Settings → MCP:

https://YOUR_PROJECT.supabase.co/functions/v1/mcp

The API and the MCP server are the same service. AI clients use MCP method names; HTTP integrations call tools/call with the same bearer token. Read the MCP server page for method names and the full tool list.

What you can do with the API

The surface covers assistants, knowledge, chat, conversations, leads, insights, workspace settings, webhooks, retrieval and audit logs. Each tool group needs at least the plan shown below.

Area	Tools	Minimum plan
Assistants	list_assistants, get_assistant, create_assistant, update_assistant, set_assistant_domains (max. 10), publish_assistant, unpublish_assistant, delete_assistant, get_embed_snippet	Growth
Knowledge	list_sources, get_source_documents, add_website_source, add_help_center_source, add_text_source, add_file_source (PDF or document in base64), sync_source, delete_source	Growth
Chat	ask_published_assistant (creates a conversation and counts toward the monthly quota), ask_assistant (also works on unpublished assistants; counts only when persist=true)	Growth
Conversations	list_conversations, get_conversation, set_conversation_status (active, answered, or needs_review), delete_conversation	Growth
Leads	list_leads, update_lead_status (new, contacted, or qualified), delete_lead	Pro
Insights	get_dashboard_metrics, get_conversations_timeseries, get_top_unanswered_questions, get_conversations_by_page, list_analytics_events (metrics accept a rolling window of 1 to 30 days)	Pro
Usage	get_usage_summary, get_entitlements	Growth
Workspace	get_workspace, update_workspace, delete_workspace, list_members, get_profile, update_profile, list_notifications, mark_notifications_read, search_workspace	Growth
Webhooks	list_integrations, connect_webhook, test_webhook, disconnect_webhook	Agency
API keys	list_api_keys (any role), create_api_key, revoke_api_key (owner or admin)	Growth
Retrieval	search_knowledge, retrieve_chunks	Growth
Jobs and audit	list_jobs, get_sync_status, list_audit_logs	Growth
Team	invite_member, change_member_role, remove_member	Agency
Client workspaces	list_workspaces (any role; lists the client workspaces you can access)	Growth
Client workspaces	create_client_workspace	Agency

• Ask your assistant and get its sources. ask_published_assistant or ask_assistant return a conversation_id, a reply object and sources pointing at the passages used. Published asks count toward your monthly conversation quota; ask_assistant only counts when persist=true.
• Search knowledge without a reply. search_knowledge and retrieve_chunks return ranked chunks with title, URL, snippet and similarity. They need an assistant_id and accept a query up to 200 characters.
• Manage sources. Add a website, help center, plain text or PDF with add_website_source, add_help_center_source, add_text_source or add_file_source, then refresh with sync_source.
• Read conversations, leads and insights. List and inspect conversations and update statuses; on Pro or Agency read leads and dashboard metrics with list_leads and get_dashboard_metrics.
• Publish and embed. Connect sources and domains, call publish_assistant (needs at least one source and one allowed domain), then get_embed_snippet. See how to add an AI assistant to your website.

Your first request

Authenticate with a bearer token (create a key under Settings → API), then POST a tools/call request for ask_assistant:

curl -sS -X POST 'https://YOUR_PROJECT.supabase.co/functions/v1/mcp' \
  -H 'Authorization: Bearer cw_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ask_assistant",
      "arguments": {
        "assistant_id": "YOUR_ASSISTANT_ID",
        "message": "What is on your pricing page?",
        "persist": false
      }
    }
  }'

A successful reply includes structured content such as conversation_id, reply (with content and status) and sources. When the assistant cannot answer from its sources, the conversation status can be needs_review.

Limits and errors

Rate limits and payload sizes apply to every key:

Limit	Value
MCP requests per API key	60/min
Failed auth attempts per IP	30/min
ask_assistant / ask_published_assistant	20/min
Knowledge source creates	15/hour
test_webhook	10/hour
API key creation	10/hour
JSON-RPC body (ordinary calls)	64,000 bytes
JSON-RPC body (add_file_source)	1,048,576 bytes
Uploaded file (decoded)	786,432 bytes
Chat message length	2,000 characters

Common HTTP and JSON-RPC outcomes. Authentication and transport use real HTTP status codes; once you are authenticated, anything a tool raises comes back as HTTP 200 carrying a JSON-RPC error — except a tool-level rate limit, which is still returned as HTTP 429:

• 401 UNAUTHENTICATED — missing, invalid, revoked or expired key. See authentication.
• 402 PLAN_REQUIRED — the workspace has no active paid plan (Growth, Pro or Agency).
• 429 RATE_LIMITED — rate limit exceeded; responses include Retry-After per RFC 9110.

A malformed request is also rejected at the HTTP layer (400 when the body cannot be parsed as JSON, 413 for an oversized body). Valid JSON that is not a JSON-RPC 2.0 request, and any other failure once a call reaches a tool, comes back as HTTP 200 with a JSON-RPC error object — top-level code -32000, and a data.code naming the cause:

• PLAN_LIMIT_REACHED — the monthly conversation quota is used up on a persisted ask.
• FORBIDDEN or PLAN_FEATURE — a role or plan gate (for example Pro-only lead tools on Growth).
• NOT_FOUND — an unknown tool, or an assistant, source or conversation not in the workspace bound to the key.

Send keys in the Authorization: Bearer header as described in RFC 6750 and the OWASP API Security Project.

Which plan includes the API

MCP and API access need an active paid plan — there is no free chatbot API, and Free workspaces receive PLAN_REQUIRED. Prices come straight from the product catalog:

Plan	Price
Growth	$29 / month
Pro	$49 / month
Agency	$200 / month

Compare features on pricing. For workflow ideas, see MCP use cases, training a chatbot on your website and the FAQ.