Skip to Content
Baseera Docs

Feedback

Let an end user rate an assistant reply with a thumbs up or down and an optional reason.

Rate an answer

POST /v0/sessions/{sessionId}/messages/{messageId}/feedback

Browser request with a publishable key, an allowed origin and a verified user token. A dev-mode anonymous session, which has no token, is refused with 401 invalid_user_token.

Prop

Type

curl -X POST "$BASEERA_URL/v0/sessions/ses_01JC9X4M2K8Q/messages/msg_a1/feedback" \
  -H "Origin: https://app.example.com" \
  -H "x-baseera-key: $BASEERA_PUBLISHABLE_KEY" \
  -H "x-baseera-user-token: $USER_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "rating": "down", "reason": "The answer used the old price." }'

Response, 200 OK:

{ "rating": "down" }

Rules

  • messageId must be an assistant message of that session whose turn has finished. Otherwise: turn_not_found (404), or turn_in_progress (409) while the message is still being written.
  • The session must be this user's and this agent's, or you get session_not_found (404).
  • One rating per turn. Rating again replaces the earlier one, including changing a thumbs up to a thumbs down.
  • A reason that breaks the rules is invalid_request (400), and the message never repeats it.
  • Anything shaped like a key is replaced before storage. The reason is untrusted text from an end user. It is never given to a model and never logged.
  • Limits: 30 ratings a minute per user and 600 per agent (429 rate_limited with Retry-After). Body at most 8 KB.

What happens to a rating

The rating is linked to the turn, so to its trace and record. In the console you can filter the sessions list by thumbs down, and save a thumbs-down turn as an eval test case from the session page.

In @baseera/react, useBaseeraFeedback() returns rate(messageId, rating, reason?) and the current ratings. <BaseeraSurface> shows thumbs under every finished reply.

Next steps

On this page