API reference

Query endpoint.

Full reference for POST /functions/v1/query-chatbot. Use this when you want a custom UI instead of the default widget.

Endpoint

bash

curl https://[project].supabase.co/functions/v1/query-chatbot \
  -H "Content-Type: application/json" \
  -d '{"chatbot_id":"<id>","token":"<embed_token>","query":"What is your return policy?"}'

Request body

Field	Type	Required	Description
`chatbot_id`	string	Yes	UUID of the chatbot. Get this from the widget-config response.
`token`	string	Yes	Embed token from dashboard → Embed tab.
`query`	string	Yes	Visitor question. Truncated to 500 characters server-side.
`conversation_history`	array	No	Previous turns for multi-turn chat. Each item is `{"role":"user"\|"assistant","content":"…"}`. The last 8 turns are used.

Response

json

{
  "answer": "You can request a refund within 7 days...",
  "show_branding": true
}

The default widget displays the answer only. Retrieval metadata is reserved for internal logging and dashboard analytics.

No-answer behavior

If the best matching document chunks are below the answer threshold, the endpoint returns a helpful fallback instead of inventing an answer. This protects trust. Add the missing content to your documents, then re-upload or reprocess the file.

Rate limits

Query limits are enforced monthly per account plan. See Rate limits for current plan limits.

Errors

Status	Meaning
`400`	Missing or invalid request fields.
`401`	Invalid embed token.
`429`	Monthly query limit exceeded.
`503`	Chatbot is not ready or model provider is unavailable.