Rate an assistant message

POST 
/api/v1/llm/rate-message

Records the caller's rating on an assistant-generated message. One entry is stored per rater per message; re-rating replaces only the caller's previous entry.

Serialize re-rating and withdrawal actions and reconcile stored state: uniqueness does not guarantee ordering against a delayed request or analytics event.

The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.

Use this in a guide: Collect message feedback · Feedback and score attribution

Request

Responses

200

Rating recorded

Give an existing assistant message a positive thumb rating; replace its sequence number.

Section ID: DOC-MA-conversations-api-rateMessage#example-conversations-rateMessage-request

Request example

{
  "conversationKey": "example_123",
  "messageSequence": "1",
  "kind": "FEEDBACK_KIND_THUMB",
  "thumbUp": true
}

Guide request for Save the user’s judgment beside the reply. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-rateMessage#example-cookbook-insights-evaluation-message-feedback-01-request

Request example

{
  "conversationKey": "support-chat-001",
  "messageSequence": 8,
  "kind": "FEEDBACK_KIND_THUMB",
  "thumbUp": true
}

Guide request for Variant: use a 1–10 scale instead of thumbs. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-rateMessage#example-cookbook-insights-evaluation-message-feedback-json-02-request

Request example

{
  "conversationKey": "support-chat-001",
  "messageSequence": 8,
  "kind": "FEEDBACK_KIND_SCALE",
  "rating": 9,
  "reason": "Answered the question and cited the policy."
}

Illustrative response shape; omitted default fields and actual outcomes depend on the operation.

Section ID: DOC-MA-conversations-api-rateMessage#example-conversations-rateMessage-response

Response example

{
  "ratedMessage": {
    "role": "ROLE_SYSTEM",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Example text",
        "cachePreferred": true
      }
    ],
    "toolCalls": [
      {
        "id": "example_123",
        "name": "example",
        "status": "TOOL_EXECUTION_STATUS_PENDING",
        "serverId": "example_123",
        "isClientTool": true,
        "description": "example",
        "approvedBy": "example",
        "endReason": "example"
      }
    ],
    "name": "example",
    "timestamp": "2026-09-16T12:00:00Z",
    "messageId": "example_123",
    "annotations": [
      {
        "kind": "ANNOTATION_KIND_URL_CITATION"
      }
    ],
    "sequence": "1",
    "generatedBy": "example",
    "usage": {
      "promptTokens": 1,
      "completionTokens": 1,
      "totalTokens": 1,
      "costEstimate": 1,
      "isByok": true
    },
    "model": "example",
    "generationContext": {
      "languagePreference": "en-US",
      "resolvedSystemPrompt": "Example text",
      "profileId": "example_123",
      "model": "example",
      "promptSource": "PROMPT_SOURCE_CLIENT_OVERRIDE",
      "profileVersion": 1,
      "fragmentsVersion": 1,
      "profileRenderFailed": true,
      "resolvedPromptHash": "Example text",
      "resolvedUserContext": "Example text"
    },
    "clientContext": {},
    "feedback": [
      {
        "kind": "FEEDBACK_KIND_THUMB",
        "thumbUp": true,
        "reason": "example",
        "ratedBy": "example"
      }
    ],
    "sourceUserMessageId": "example_123",
    "finishReason": "example"
  },
  "isUpdate": true
}

Illustrative response for Save the user’s judgment beside the reply. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-rateMessage#example-cookbook-insights-evaluation-message-feedback-json-01-response

Response example

{
  "ratedMessage": {
    "role": "ROLE_ASSISTANT",
    "sequence": "8",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "…"
      }
    ],
    "feedback": [
      {
        "kind": "FEEDBACK_KIND_THUMB",
        "thumbUp": true,
        "ratedAt": "2026-08-14T11:02:44Z",
        "ratedBy": "user_123"
      }
    ]
  },
  "isUpdate": true
}

Document ID: DOC-MA-conversations-api-rateMessage. Section identities and revisions.

Section	Stable reference
Rate an assistant message	DOC-MA-conversations-api-rateMessage#overview
Request	DOC-MA-conversations-api-rateMessage#request
Responses	DOC-MA-conversations-api-rateMessage#responses