> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mithunai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate an answer in a widget thread

> Set or replace the visitor's thumbs-up or thumbs-down on one answer in their own thread, with an optional note. A thumbs down appears in the unanswered-questions report.

Sets the visitor's rating of one answer in a thread they hold the token for, or replaces the rating already there. Only an answer can be rated: rating a question returns `400`. A thread has one visitor, so an answer has at most one rating.

A rating of `down` puts the question that was answered into [List unanswered questions](/api-reference/analytics/list-unanswered) with the reason `rated_unhelpful`, where an Owner or Administrator reads it with the note. See [Analytics](/administration/analytics).

Call this from the visitor's browser. It takes the embed's **public widget key** in `X-ARUKZ-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](/channels/widget).

You must also send the thread's `X-ARUKZ-Visitor-Token`. The token is checked first: a missing token, another thread's token, an unknown conversation ID and a malformed ID all return the same `404`, so one visitor cannot rate, read or clear another visitor's rating.

<ParamField path="conversation_id" type="string" required>
  The conversation's ID (UUID), from [Start a widget
  conversation](/api-reference/widget/start-thread).
</ParamField>

<ParamField path="message_id" type="string" required>
  The answer's `id` (UUID), from [Send a widget message](/api-reference/widget/send-thread-message)
  or [List widget messages](/api-reference/widget/list-thread-messages).
</ParamField>

<ParamField header="X-ARUKZ-Widget-Key" type="string" required>
  The deployment's public widget key, `arukz_wk_…`.
</ParamField>

<ParamField header="X-ARUKZ-Visitor-Token" type="string" required>
  The visitor token returned when this thread was started.
</ParamField>

<ParamField header="Origin" type="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.
</ParamField>

<ParamField body="rating" type="string" required>
  `up` or `down`. Any other value returns `400`.
</ParamField>

<ParamField body="note" type="string">
  An optional note, stored as plain text, of up to 1,000 characters. Leading and trailing space is
  removed, and a blank note is stored as none. Control characters are refused.
</ParamField>

## Response

The stored rating.

<ResponseField name="id" type="string" required>The rating's ID.</ResponseField>
<ResponseField name="message_id" type="string" required>The answer that was rated.</ResponseField>
<ResponseField name="conversation_id" type="string" required>The thread the answer belongs to.</ResponseField>
<ResponseField name="rating" type="string" required>`up` or `down`.</ResponseField>
<ResponseField name="note" type="string | null" required>The note sent with the rating, or `null`.</ResponseField>
<ResponseField name="actor" type="object" required>`{"type": "widget", "id": <deployment ID>}`. One embed is one principal; nothing identifies the visitor.</ResponseField>
<ResponseField name="created_at" type="string" required>ISO 8601 in UTC.</ResponseField>
<ResponseField name="updated_at" type="string" required>ISO 8601 in UTC.</ResponseField>

<RequestExample>
  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Runs on your website.
  const MITHUNAI_API = `${MITHUNAI_URL}/mithunai/api/v1`
  const WIDGET_KEY = 'arukz_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e'
  const conversationId = sessionStorage.getItem('mithunai.conversation')
  const messageId = '3f8a1c6d-9e24-4b70-8d5f-a1b2c3d4e5f6' // answer.id from the turn

  const response = await fetch(
    `${MITHUNAI_API}/widget/conversations/${conversationId}/messages/${messageId}/feedback`,
    {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
        'X-ARUKZ-Widget-Key': WIDGET_KEY,
        'X-ARUKZ-Visitor-Token': sessionStorage.getItem('mithunai.visitorToken'),
      },
      body: JSON.stringify({ rating: 'down', note: 'This describes the old dashboard.' }),
    },
  )
  console.log(await response.json())
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request PUT "$MITHUNAI_URL/mithunai/api/v1/widget/conversations/0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a/messages/3f8a1c6d-9e24-4b70-8d5f-a1b2c3d4e5f6/feedback" \
    --header "Content-Type: application/json" \
    --header "X-ARUKZ-Widget-Key: arukz_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e" \
    --header "X-ARUKZ-Visitor-Token: $VISITOR_TOKEN" \
    --header "Origin: https://docs.example.com" \
    --data '{ "rating": "down", "note": "This describes the old dashboard." }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "b7c2e9a4-5d18-4f63-9a0e-2c4d6f8b1e37",
    "message_id": "3f8a1c6d-9e24-4b70-8d5f-a1b2c3d4e5f6",
    "conversation_id": "0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a",
    "rating": "down",
    "note": "This describes the old dashboard.",
    "actor": { "type": "widget", "id": "8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e" },
    "created_at": "2026-10-12T10:02:41.118204+00:00",
    "updated_at": "2026-10-12T10:02:41.118204+00:00"
  }
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "validation_error", "message": "'rating' must be 'up' or 'down'." }
  ```

  ```json 401 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "authentication_error", "message": "Authentication is required." }
  ```

  ```json 403 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "authorization_error", "message": "This widget may not be embedded from that origin." }
  ```

  ```json 404 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "not_found", "message": "The requested resource was not found." }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.