Skip to main content

​
Overview

The feedback submission endpoints allow users to provide feedback on assistant responses through a simple thumbs up/down mechanism. When auto-approval is enabled, positive feedback automatically creates golden examples for continuous model improvement.

​
Feedback Lifecycle

Feedback goes through the following states:
  1. Pending - Initial state when feedback is submitted
  2. Auto-approved - Automatically approved based on settings (creates golden example)
  3. Reviewed - Manually reviewed and resolved by admin (creates golden example)
  4. Dismissed - Reviewed but not used for improvement
When auto-approval is enabled for a feedback type, golden examples are automatically created upon submission, allowing the system to learn from user preferences in real-time.

​
Submit Feedback

​
Request Body

​
message_id
string
required
ID of the message being rated
​
feedback_type
string
required
Type of feedback. Must be either positive or negative
​
reason
string
Optional reason for the feedback. May be required based on settings

​
Response

​
id
string
Unique identifier for the feedback
​
message_id
string
ID of the message that was rated
​
user_id
string
ID of the user who submitted the feedback
​
feedback_type
string
Type of feedback: positive or negative
​
reason
string | null
The reason provided for the feedback
​
status
string
Current status: pending, auto_approved, reviewed, or dismissed
​
reviewed_by
string | null
ID of the admin who reviewed the feedback (null if not reviewed)
​
reviewed_at
datetime | null
Timestamp when the feedback was reviewed (null if not reviewed)
​
created_at
datetime
Timestamp when the feedback was created

​
Example Request

curl -X POST https://api.example.com/feedback \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "550e8400-e29b-41d4-a716-446655440000",
    "feedback_type": "positive",
    "reason": "Very helpful and accurate response"
  }'

​
Example Response

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "feedback_type": "positive",
  "reason": "Very helpful and accurate response",
  "status": "auto_approved",
  "reviewed_by": null,
  "reviewed_at": null,
  "created_at": "2026-03-01T10:30:00Z"
}
If auto-approval is enabled for this feedback type, the status will be auto_approved and a golden example is automatically created in the background.

​
Get Feedback for Message

​
Path Parameters

​
message_id
string
required
ID of the message to get feedback for

​
Response

Returns a FeedbackResponse object if feedback exists, or null if the user hasn’t provided feedback for this message.
​
id
string
Unique identifier for the feedback
​
message_id
string
ID of the message that was rated
​
user_id
string
ID of the user who submitted the feedback
​
feedback_type
string
Type of feedback: positive or negative
​
reason
string | null
The reason provided for the feedback
​
status
string
Current status: pending, auto_approved, reviewed, or dismissed
​
reviewed_by
string | null
ID of the admin who reviewed the feedback
​
reviewed_at
datetime | null
Timestamp when the feedback was reviewed
​
created_at
datetime
Timestamp when the feedback was created

​
Example Request

curl -X GET https://api.example.com/feedback/message/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "feedback_type": "positive",
  "reason": "Very helpful and accurate response",
  "status": "auto_approved",
  "reviewed_by": null,
  "reviewed_at": null,
  "created_at": "2026-03-01T10:30:00Z"
}

​
Example Response (No Feedback)

null

​
Error Responses

​
400 Bad Request

Returned when the request is invalid: 
{
  "detail": "Invalid feedback type. Must be 'positive' or 'negative'"
}

​
401 Unauthorized

Returned when authentication is missing or invalid: 
{
  "detail": "Not authenticated"
}

​
404 Not Found

Returned when the message doesn’t exist: 
{
  "detail": "Message not found"
}

​
500 Internal Server Error

Returned when an unexpected error occurs: 
{
  "detail": "Failed to submit feedback"
}

​
Best Practices

Check Existing Feedback

Use the GET endpoint to check if the user has already provided feedback before showing the feedback UI.

Provide Context

Include a meaningful reason when submitting negative feedback to help improve responses.

Handle Auto-Approval

Be aware that positive feedback may be auto-approved based on settings, immediately contributing to model improvement.

Error Handling

Implement proper error handling for network failures and validation errors.

​
Auto-Approval System

The auto-approval system allows organizations to automatically create golden examples from user feedback:
  • Positive Feedback: When auto-approved, the original response becomes a golden example
  • Negative Feedback: Can be auto-approved with admin review for the corrected response
  • Settings Control: Admins can configure auto-approval per feedback type via settings endpoints
Enable auto-approval for positive feedback to build your golden examples dataset automatically as users interact with the assistant.

Build docs developers (and LLMs) love

Get started for freeTalk to us