Rate an assistant answer · Ownrecord docs

Rates one of the assistant's answers in your own conversation: thumbs up or down, with an optional comment (at most 1,000 characters). Rating again replaces the earlier rating. Rated answers help Ownrecord test the assistant; they are anonymised before they leave your organization.

Who can call it: the conversation's owner, signed in.

At a glance

REST: POST /api/v1/assistant/conversations/{conversationId}/messages/{messageId}/rating
MCP tool: assistant_messages_rate
Operation ID: assistant.messages.rate
Scope: Platform
Permission: account:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the account:write scope
Since: M11

Request

Path parameters

Field	Type	Description
`conversationId`	`aconv_…` ID	The conversation (`aconv_…`).
`messageId`	`amsg_…` ID	The assistant's answer (`amsg_…`).

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`rating`	one of `up`, `down`	Yes
`comment`	string	No

Response

200 OK with a JSON object:

Field	Type	Description
`id`	`amsg_…` ID
`object`	`"assistant_message"`
`role`	one of `user`, `assistant`, `tool`
`content`	string
`parts`	array of object	The answer's citations, tool activity, action cards, results and refusals (the assistant protocol).
`rating`	object or null
`createdAt`	date-time

Examples

Thumbs up

HTTP

POST /api/v1/assistant/conversations/aconv_01jbz3k6q2e8w1m0v9r7t5y4x3/messages/amsg_01jbz3k6q9h8g7f6e5d4c3b2a1/rating
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "rating": "up"
}

Response (200):

JSON

{
  "id": "amsg_01jbz3k6q9h8g7f6e5d4c3b2a1",
  "object": "assistant_message",
  "role": "assistant",
  "content": "I've prepared the coupon. Review the preview on the card, then click **Confirm** to run it.",
  "parts": [
    {
      "type": "action_card",
      "card": {
        "proposalId": "amsg_01jbz3k6q9h8g7f6e5d4c3b2a1:1",
        "operationId": "coupons.create",
        "inputHash": "4f6c1f0e3b2a9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a39281706f5e4d3c2b1a0",
        "title": "Create a coupon",
        "effect": "Create a coupon (name: 20% off, percentOffPpm: 200000, duration: repeating), in test mode.",
        "riskTier": "write",
        "preview": {
          "kind": "generic",
          "result": {
            "name": "20% off",
            "percentOffPpm": 200000
          }
        },
        "requiresFreshAuth": false,
        "status": "executed"
      }
    }
  ],
  "rating": {
    "value": "up",
    "comment": null
  },
  "createdAt": "2026-10-26T09:16:10.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	An ID is malformed, or the comment is too long.	Fix the fields listed in `details.issues` and send the request again.
`conversation_not_found`	404	No such conversation of yours.	Start a new conversation. Conversations are deleted after the organization's retention period, and only their owner can open them.
`resource_not_found`	404	The message isn't an answer of this conversation.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`permission_denied`	403	The caller isn't a signed-in person (an API key or OAuth token).	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Thumbs up#

Errors#