List one visitor's own widget threads
The widget threads belonging to the visitor token you present, and no others. A visitor cannot list another’s threads by changing an identifier.
GET
/
widget
/
conversations
// Runs on your website.
const MITHUNAI_API = `${MITHUNAI_URL}/mithunai/api/v1`
const WIDGET_KEY = 'mithunai_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e'
const response = await fetch(`${MITHUNAI_API}/widget/conversations`, {
headers: {
'X-MITHUNAI-Widget-Key': WIDGET_KEY,
'X-MITHUNAI-Visitor-Token': sessionStorage.getItem('mithunai.visitorToken'),
},
})
const { data } = await response.json()
console.log(data)
curl --request GET "$MITHUNAI_URL/mithunai/api/v1/widget/conversations?limit=20" \
--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"
{
"data": [
{
"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" }
}
],
"next_cursor": null,
"has_more": false
}
{ "code": "validation_error", "message": "'limit' must be between 1 and 100." }
{ "code": "authentication_error", "message": "Authentication is required." }
{ "code": "authorization_error", "message": "This widget may not be embedded from that origin." }
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.
Only threads started with the visitor token you send are returned. Without an X-MITHUNAI-Visitor-Token header the response is an empty list, never other visitors’ threads. A visitor token belongs to one thread, so in practice this returns at most the one conversation that token unlocks.
The server reads the embed’s threads across all visitors, newest first, and keeps only the ones your token unlocks. It stops once it has limit of them, or after the embed’s 500 newest threads. On an embed busier than that, an older thread can be missing from the result even though its token is valid; fetch it directly with Get a widget conversation instead. This endpoint returns a single page: next_cursor is always null and has_more is always false.
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 deployment’s public widget key,
mithunai_wk_….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
The visitor token returned when a thread was started. Without it the list is empty.
boolean
default:"false"
Include archived threads. Accepts
true, false, 1 or 0, in any letter case. Any other value
returns 400 validation_error.integer
default:"20"
How many of the embed’s most recent threads to consider, from 1 to 100.
Response
object[]
required
The threads your token unlocks, newest first.
Show properties
Show properties
string
required
The conversation’s ID (UUID).
string
required
The assistant the deployment embeds.
string
required
The thread’s title.
string
required
active or archived.string
required
idle when ready for a question, or awaiting_answer while an answer is being generated.integer
required
Number of messages, questions and answers together.
string
required
ISO 8601 in UTC.
string
required
ISO 8601 in UTC.
object
required
{"type": "widget", "id": <deployment ID>}.object
required
The metadata sent when the thread was started.
string | null
required
Always
null.boolean
required
Always
false.// Runs on your website.
const MITHUNAI_API = `${MITHUNAI_URL}/mithunai/api/v1`
const WIDGET_KEY = 'mithunai_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e'
const response = await fetch(`${MITHUNAI_API}/widget/conversations`, {
headers: {
'X-MITHUNAI-Widget-Key': WIDGET_KEY,
'X-MITHUNAI-Visitor-Token': sessionStorage.getItem('mithunai.visitorToken'),
},
})
const { data } = await response.json()
console.log(data)
curl --request GET "$MITHUNAI_URL/mithunai/api/v1/widget/conversations?limit=20" \
--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"
{
"data": [
{
"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" }
}
],
"next_cursor": null,
"has_more": false
}
{ "code": "validation_error", "message": "'limit' must be between 1 and 100." }
{ "code": "authentication_error", "message": "Authentication is required." }
{ "code": "authorization_error", "message": "This widget may not be embedded from that origin." }
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 response = await fetch(`${MITHUNAI_API}/widget/conversations`, {
headers: {
'X-MITHUNAI-Widget-Key': WIDGET_KEY,
'X-MITHUNAI-Visitor-Token': sessionStorage.getItem('mithunai.visitorToken'),
},
})
const { data } = await response.json()
console.log(data)
curl --request GET "$MITHUNAI_URL/mithunai/api/v1/widget/conversations?limit=20" \
--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"
{
"data": [
{
"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" }
}
],
"next_cursor": null,
"has_more": false
}
{ "code": "validation_error", "message": "'limit' must be between 1 and 100." }
{ "code": "authentication_error", "message": "Authentication is required." }
{ "code": "authorization_error", "message": "This widget may not be embedded from that origin." }