Ask a question from the website widget
Ask a question in a widget thread and wait for the complete cited answer. Takes the widget key, the visitor token and an allowed Origin.
POST
/
widget
/
conversations
/
{conversation_id}
/
messages
// Runs on your website.
const MITHUNAI_API = `${MITHUNAI_URL}/mithunai/api/v1`
const WIDGET_KEY = 'mithunai_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e'
const conversationId = sessionStorage.getItem('mithunai.conversation')
const response = await fetch(`${MITHUNAI_API}/widget/conversations/${conversationId}/messages`, {
method: 'POST',
headers: {
'X-MITHUNAI-Widget-Key': WIDGET_KEY,
'X-MITHUNAI-Visitor-Token': sessionStorage.getItem('mithunai.visitorToken'),
'Content-Type': 'application/json',
},
body: JSON.stringify({
text: 'How do I raise my rate limit?',
idempotency_key: crypto.randomUUID(),
}),
})
const { answer } = await response.json()
console.log(answer.text, answer.citations)
curl --request POST "$MITHUNAI_URL/mithunai/api/v1/widget/conversations/0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a/messages" \
--header "X-MITHUNAI-Widget-Key: mithunai_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e" \
--header "X-MITHUNAI-Visitor-Token: $VISITOR_TOKEN" \
--header "Origin: https://docs.example.com" \
--header "Content-Type: application/json" \
--data '{"text": "How do I raise my rate limit?", "idempotency_key": "q-7f3c1e"}'
{
"conversation": {
"id": "0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a",
"assistant_id": "5b1e9c2a-7d4f-4e3b-9a61-0c8f2d7e4a13",
"title": "How do I raise my rate limit?",
"status": "active",
"turn_state": "idle",
"message_count": 2,
"created_at": "2026-09-24T10:02:17.559310+00:00",
"updated_at": "2026-09-24T10:02:24.910447+00:00",
"owner": { "type": "widget", "id": "8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e" },
"metadata": { "page": "/guides/rate-limits" }
},
"question": {
"id": "4a1b2c3d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"conversation_id": "0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a",
"role": "user",
"sequence": 1,
"status": "complete",
"text": "How do I raise my rate limit?",
"citations": [],
"abstained": false,
"created_at": "2026-09-24T10:02:21.004118+00:00",
"model": null,
"finish_reason": null,
"idempotency_key": "q-7f3c1e",
"metadata": {}
},
"answer": {
"id": "9f8e7d6c-5b4a-4c3d-9e2f-1a0b9c8d7e6f",
"conversation_id": "0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a",
"role": "assistant",
"sequence": 2,
"status": "complete",
"text": "Rate limits are set per plan. To request a higher limit, open a support ticket from the billing page and include your expected peak requests per minute [1].",
"citations": [
{
"source_id": "6e1d3c5b-9a7f-4b2e-8d0c-3f5a7b9d1e2f",
"ordinal": 1,
"title": "Rate limits",
"url": "https://docs.example.com/guides/rate-limits",
"snippet": "To request a higher limit, open a support ticket from the billing page.",
"anchor": "requesting-a-higher-limit",
"score": 0.82
}
],
"abstained": false,
"created_at": "2026-09-24T10:02:21.004118+00:00",
"model": "anthropic/claude-sonnet-5",
"finish_reason": "stop",
"idempotency_key": null,
"metadata": {}
}
}
{ "code": "validation_error", "message": "A message must contain text." }
{ "code": "authentication_error", "message": "Authentication is required." }
{ "code": "authorization_error", "message": "This widget may not be embedded from that origin." }
{ "code": "not_found", "message": "The requested resource was not found." }
{ "code": "conflict", "message": "This conversation is already waiting for an answer." }
{ "code": "rate_limit_exceeded", "message": "Too many requests. Please retry later." }
{
"code": "quota_exceeded",
"message": "The monthly answer limit for this account has been reached."
}
Call this from the visitor’s browser. It takes the embed’s public widget key in
X-MITHUNAI-Widget-Key, and the browser’s Origin must be allowed by both the deployment’s allowed_origins and the platform-wide widget allowlist. See Website widget.
You must also send the thread’s X-MITHUNAI-Visitor-Token. The token is checked before the question is recorded or any model is called. A missing token, another thread’s token and an unknown conversation all return the same 404.
The answer is generated from the assistant’s own knowledge, with citations. When the knowledge does not contain the answer, the assistant abstains: the response is still 201, with answer.abstained set to true and no citations. See How answers work.
When the organisation has used its monthly answer allowance, a question is refused with 429 and the code quota_exceeded; the widget tells the visitor the limit has been reached and offers no retry.
A thread answers one question at a time. Sending a question while the previous answer is still being generated returns 409. To retry safely after a dropped connection, send the same idempotency_key: if that question was already answered, you get the original turn back and the model is not called again. To show the answer as it is written, use Stream a widget message instead.
A refusal made before the key and the origin are accepted (a missing or invalid key, an origin the deployment does not allow, or the per-address limit checked before the key is read) carries no Access-Control-Allow-Origin header, so in a cross-origin browser request fetch rejects with a network error instead of exposing the error body. Once the key is accepted and the origin is allowed, every response carries the header, refusals included, so your page can read a 404, a 429 and its Retry-After.
string
required
The conversation’s ID (UUID).
string
required
The deployment’s public widget key,
mithunai_wk_….string
required
The visitor token returned when this thread was started.
string
required
Set by the browser. It must exactly match an origin allowed for this deployment. When you call
from outside a browser, set it yourself.
string
required
The question. Up to 16,000 characters, and not empty after surrounding whitespace is trimmed.
Newlines and tabs are allowed; other control characters are refused.
string
Your own key for this question, up to 128 characters of
A-Z, a-z, 0-9, _, ., : and
-. Resending a key that was already answered in this thread returns that earlier turn instead of
asking again.object
Your own string labels for the question. At most 20 entries; keys are 1 to 64 characters of
lowercase
a-z, 0-9, _, . and -, starting with a letter; values are up to 512 characters.Response
Returns201 Created with the updated conversation, the question and the answer.
object
required
The conversation after this turn, with the same fields as Get a widget
conversation. If the thread was started without a title, its
title is taken from the first line of the first question, shortened to 80 characters.object
required
The visitor’s message, with
role set to user. Same fields as answer.object
required
The assistant’s message.
Show properties
Show properties
string
required
The message’s ID (UUID).
string
required
The conversation it belongs to.
string
required
assistant.integer
required
Position in the conversation.
string
required
complete for a finished answer.string
required
The answer, with
[n] markers that match citations[].ordinal.object[]
required
Sources the answer is grounded in. Empty when the assistant abstained.
Show properties
Show properties
string
Identifier of the cited passage. It stays the same while the document’s content is
unchanged and changes when changed content is re-ingested. It is not a knowledge source ID
or a document ID.
integer
The citation’s number.
string
Document title. May be an empty string.
string | null
Link to the source.
string | null
The passage the answer relied on.
string | null
Section anchor within the source.
number | null
Retrieval relevance score.
boolean
required
true when the knowledge did not contain the answer.string
required
ISO 8601 in UTC.
string | null
required
The model that produced the answer.
string | null
required
Why generation ended, for example
stop, or length when the answer was truncated.string | null
required
Always
null on an answer; the key is recorded on the question.object
required
Always
{} on an answer.// Runs on your website.
const MITHUNAI_API = `${MITHUNAI_URL}/mithunai/api/v1`
const WIDGET_KEY = 'mithunai_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e'
const conversationId = sessionStorage.getItem('mithunai.conversation')
const response = await fetch(`${MITHUNAI_API}/widget/conversations/${conversationId}/messages`, {
method: 'POST',
headers: {
'X-MITHUNAI-Widget-Key': WIDGET_KEY,
'X-MITHUNAI-Visitor-Token': sessionStorage.getItem('mithunai.visitorToken'),
'Content-Type': 'application/json',
},
body: JSON.stringify({
text: 'How do I raise my rate limit?',
idempotency_key: crypto.randomUUID(),
}),
})
const { answer } = await response.json()
console.log(answer.text, answer.citations)
curl --request POST "$MITHUNAI_URL/mithunai/api/v1/widget/conversations/0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a/messages" \
--header "X-MITHUNAI-Widget-Key: mithunai_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e" \
--header "X-MITHUNAI-Visitor-Token: $VISITOR_TOKEN" \
--header "Origin: https://docs.example.com" \
--header "Content-Type: application/json" \
--data '{"text": "How do I raise my rate limit?", "idempotency_key": "q-7f3c1e"}'
{
"conversation": {
"id": "0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a",
"assistant_id": "5b1e9c2a-7d4f-4e3b-9a61-0c8f2d7e4a13",
"title": "How do I raise my rate limit?",
"status": "active",
"turn_state": "idle",
"message_count": 2,
"created_at": "2026-09-24T10:02:17.559310+00:00",
"updated_at": "2026-09-24T10:02:24.910447+00:00",
"owner": { "type": "widget", "id": "8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e" },
"metadata": { "page": "/guides/rate-limits" }
},
"question": {
"id": "4a1b2c3d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"conversation_id": "0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a",
"role": "user",
"sequence": 1,
"status": "complete",
"text": "How do I raise my rate limit?",
"citations": [],
"abstained": false,
"created_at": "2026-09-24T10:02:21.004118+00:00",
"model": null,
"finish_reason": null,
"idempotency_key": "q-7f3c1e",
"metadata": {}
},
"answer": {
"id": "9f8e7d6c-5b4a-4c3d-9e2f-1a0b9c8d7e6f",
"conversation_id": "0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a",
"role": "assistant",
"sequence": 2,
"status": "complete",
"text": "Rate limits are set per plan. To request a higher limit, open a support ticket from the billing page and include your expected peak requests per minute [1].",
"citations": [
{
"source_id": "6e1d3c5b-9a7f-4b2e-8d0c-3f5a7b9d1e2f",
"ordinal": 1,
"title": "Rate limits",
"url": "https://docs.example.com/guides/rate-limits",
"snippet": "To request a higher limit, open a support ticket from the billing page.",
"anchor": "requesting-a-higher-limit",
"score": 0.82
}
],
"abstained": false,
"created_at": "2026-09-24T10:02:21.004118+00:00",
"model": "anthropic/claude-sonnet-5",
"finish_reason": "stop",
"idempotency_key": null,
"metadata": {}
}
}
{ "code": "validation_error", "message": "A message must contain text." }
{ "code": "authentication_error", "message": "Authentication is required." }
{ "code": "authorization_error", "message": "This widget may not be embedded from that origin." }
{ "code": "not_found", "message": "The requested resource was not found." }
{ "code": "conflict", "message": "This conversation is already waiting for an answer." }
{ "code": "rate_limit_exceeded", "message": "Too many requests. Please retry later." }
{
"code": "quota_exceeded",
"message": "The monthly answer limit for this account has been reached."
}
Last modified on November 7, 2026
// Runs on your website.
const MITHUNAI_API = `${MITHUNAI_URL}/mithunai/api/v1`
const WIDGET_KEY = 'mithunai_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e'
const conversationId = sessionStorage.getItem('mithunai.conversation')
const response = await fetch(`${MITHUNAI_API}/widget/conversations/${conversationId}/messages`, {
method: 'POST',
headers: {
'X-MITHUNAI-Widget-Key': WIDGET_KEY,
'X-MITHUNAI-Visitor-Token': sessionStorage.getItem('mithunai.visitorToken'),
'Content-Type': 'application/json',
},
body: JSON.stringify({
text: 'How do I raise my rate limit?',
idempotency_key: crypto.randomUUID(),
}),
})
const { answer } = await response.json()
console.log(answer.text, answer.citations)
curl --request POST "$MITHUNAI_URL/mithunai/api/v1/widget/conversations/0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a/messages" \
--header "X-MITHUNAI-Widget-Key: mithunai_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e" \
--header "X-MITHUNAI-Visitor-Token: $VISITOR_TOKEN" \
--header "Origin: https://docs.example.com" \
--header "Content-Type: application/json" \
--data '{"text": "How do I raise my rate limit?", "idempotency_key": "q-7f3c1e"}'
{
"conversation": {
"id": "0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a",
"assistant_id": "5b1e9c2a-7d4f-4e3b-9a61-0c8f2d7e4a13",
"title": "How do I raise my rate limit?",
"status": "active",
"turn_state": "idle",
"message_count": 2,
"created_at": "2026-09-24T10:02:17.559310+00:00",
"updated_at": "2026-09-24T10:02:24.910447+00:00",
"owner": { "type": "widget", "id": "8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e" },
"metadata": { "page": "/guides/rate-limits" }
},
"question": {
"id": "4a1b2c3d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"conversation_id": "0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a",
"role": "user",
"sequence": 1,
"status": "complete",
"text": "How do I raise my rate limit?",
"citations": [],
"abstained": false,
"created_at": "2026-09-24T10:02:21.004118+00:00",
"model": null,
"finish_reason": null,
"idempotency_key": "q-7f3c1e",
"metadata": {}
},
"answer": {
"id": "9f8e7d6c-5b4a-4c3d-9e2f-1a0b9c8d7e6f",
"conversation_id": "0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a",
"role": "assistant",
"sequence": 2,
"status": "complete",
"text": "Rate limits are set per plan. To request a higher limit, open a support ticket from the billing page and include your expected peak requests per minute [1].",
"citations": [
{
"source_id": "6e1d3c5b-9a7f-4b2e-8d0c-3f5a7b9d1e2f",
"ordinal": 1,
"title": "Rate limits",
"url": "https://docs.example.com/guides/rate-limits",
"snippet": "To request a higher limit, open a support ticket from the billing page.",
"anchor": "requesting-a-higher-limit",
"score": 0.82
}
],
"abstained": false,
"created_at": "2026-09-24T10:02:21.004118+00:00",
"model": "anthropic/claude-sonnet-5",
"finish_reason": "stop",
"idempotency_key": null,
"metadata": {}
}
}
{ "code": "validation_error", "message": "A message must contain text." }
{ "code": "authentication_error", "message": "Authentication is required." }
{ "code": "authorization_error", "message": "This widget may not be embedded from that origin." }
{ "code": "not_found", "message": "The requested resource was not found." }
{ "code": "conflict", "message": "This conversation is already waiting for an answer." }
{ "code": "rate_limit_exceeded", "message": "Too many requests. Please retry later." }
{
"code": "quota_exceeded",
"message": "The monthly answer limit for this account has been reached."
}