> ## 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 conversation

> Set or replace your thumbs-up or thumbs-down on one answer in a conversation you started, with an optional note. A thumbs down appears in the unanswered-questions report.

Sets your rating of one answer, or replaces the rating you already gave it. You can rate only in a conversation you started, and only an answer: rating a question returns `400`. Each caller has at most one rating per answer, so sending this again changes the rating and keeps its `id` and `created_at`.

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).

A conversation that does not exist, belongs to another organization or was started by someone else returns `404`, and so does a message that is not in it or a malformed ID. That includes an `owner` or `admin`, who can [read](/api-reference/conversations/list-message-ratings) the ratings on a colleague's conversation but cannot add one. A credential that cannot send messages gets `403`.

<ParamField path="conversation_id" type="string" required>
  The conversation ID.
</ParamField>

<ParamField path="message_id" type="string" required>
  The answer's `id`, from [Send a message](/api-reference/conversations/send-message) or [List
  messages](/api-reference/conversations/list-messages).
</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 conversation 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>
  Who gave the rating: `type` is `user` for a console session or `service` for an API key, and `id`
  identifies that user or key.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  When the rating was first given, ISO 8601 in UTC.
</ResponseField>

<ResponseField name="updated_at" type="string" required>
  When the rating was last set, ISO 8601 in UTC.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request PUT "$MITHUNAI_URL/mithunai/api/v1/conversations/c41f8a2e-6d93-4b0a-b7e5-3f1d2c8a9e60/messages/7c3a9e52-1b6d-4f08-a4e7-2d9b5f1c8e36/feedback" \
    --header "Authorization: Bearer $MITHUNAI_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{"rating": "down", "note": "This describes the old dashboard."}'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os, requests

  conversation_id = "c41f8a2e-6d93-4b0a-b7e5-3f1d2c8a9e60"
  message_id = "7c3a9e52-1b6d-4f08-a4e7-2d9b5f1c8e36"
  response = requests.put(
      f"{os.environ['MITHUNAI_URL']}/mithunai/api/v1/conversations/{conversation_id}/messages/{message_id}/feedback",
      headers={"Authorization": f"Bearer {os.environ['MITHUNAI_API_KEY']}"},
      json={"rating": "down", "note": "This describes the old dashboard."},
      timeout=60,
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const conversationId = 'c41f8a2e-6d93-4b0a-b7e5-3f1d2c8a9e60'
  const messageId = '7c3a9e52-1b6d-4f08-a4e7-2d9b5f1c8e36'
  const response = await fetch(
    `${process.env.MITHUNAI_URL}/mithunai/api/v1/conversations/${conversationId}/messages/${messageId}/feedback`,
    {
      method: 'PUT',
      headers: {
        Authorization: `Bearer ${process.env.MITHUNAI_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ rating: 'down', note: 'This describes the old dashboard.' }),
    },
  )
  console.log(await response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "b7c2e9a4-5d18-4f63-9a0e-2c4d6f8b1e37",
    "message_id": "7c3a9e52-1b6d-4f08-a4e7-2d9b5f1c8e36",
    "conversation_id": "c41f8a2e-6d93-4b0a-b7e5-3f1d2c8a9e60",
    "rating": "down",
    "note": "This describes the old dashboard.",
    "actor": { "type": "service", "id": "2f6b8d1c-4a35-4e79-b0c2-8d7e5f3a1b94" },
    "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 403 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "authorization_error", "message": "You do not have permission to perform this action." }
  ```

  ```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.