Skip to main content
Both shapes documented here are superseded. New integrations should follow the current console feedbacks doc. This page is kept for reference while consumers transition; the underlying Feedback rows in Mongo are still readable, but submissions and new console reads use the v2.2 shape.
The console GET /v1/console/feedbacks endpoint has been through two revamps. The path has stayed the same; the response envelope, query parameters, and submission body have all shifted.
ShapeWhenStatus
Original (flat list, no analytics, four user-supplied fields)through v2.0Deprecated
v2.1 (nested envelope, analytics block, joins)v2.1Superseded
Current (revamped form, five-rating averages)v2.2+See current doc

​
Shape 1 — Original (deprecated)

A flat PaginatedResponse[FeedbackConsoleItem]. Skip/limit pagination. Search matched only the additional_info comment field. No analytics block.

​
Submission body (the four user-supplied fields)

{
  "session_id": "...",
  "rating": 5,
  "difficulty_level": 2,
  "clarity_level": 5,
  "valuable_metric": "real-world-relevance",
  "additional_info": "..."
}
difficulty_level was scaled 1–3 (1 easy, 2 balanced, 3 hard). valuable_metric was a fixed enum: discussion-prompts, feedback-quality, real-world-relevance, time-pressure.

​
Console list response

{
  "success": true,
  "data": [
    {
      "id": "6650f1a2b3c4d5e6f7a8b9c0",
      "session_id": "6650d4e5f6a7b8c9d0e1f2a3",
      "case_study_id": "6650c3d4e5f6a7b8c9d0e1f2",
      "case_study_title": "Diabetes Patient Assessment",
      "user_id": "6650a1b2c3d4e5f6a7b8c9d0",
      "student_name": "Jane Smith",
      "student_email": "jane.smith@example.com",
      "rating": 5,
      "difficulty_level": 2,
      "clarity_level": 5,
      "valuable_metric": "real-world-relevance",
      "additional_info": "...",
      "created_at": "2026-04-10T14:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50,
  "total_pages": 1
}
Query parameters (legacy): case_study_id, user_id, min_rating, max_rating, valuable_metric, start_date, end_date, search (matched comment only), sort_by, sort_order, skip, limit.

​
Shape 2 — v2.1 (superseded)

Same submission body as Shape 1, but the console response was restructured into a nested envelope with an analytics block and richer joins.

​
Console list response (v2.1)

{
  "success": true,
  "data": {
    "filters": { "case_study_id": "...", "search": "ada" },
    "analytics": {
      "average_rating": 4.5,
      "feedback_received": 2,
      "case_studies": 1
    },
    "feedback": [
      {
        "feedback_id": "...",
        "session_id": "...",
        "student": { "student_id": "...", "name": "...", "email": "..." },
        "case_study": { "case_study_id": "...", "title": "..." },
        "rating": 5,
        "comment": "...",
        "completed_at": "2026-04-18T10:32:00Z",
        "difficulty_level": 2,
        "clarity_level": 5,
        "valuable_metric": "feedback-quality"
      }
    ],
    "pagination": { "total": 1, "page": 1, "page_size": 10, "total_pages": 1 }
  },
  "message": "Student feedback retrieved successfully."
}
skip was replaced by 1-based page. Search expanded to match student name / email / case study title. The submission body and the four user-supplied fields stayed identical to Shape 1.

​
What changed in v2.2 (current)

v2.1 → v2.2 (current)
valuable_metric (enum) → most_valuable (free text, optional)
difficulty_level 1–3 → 1–5
Added: overall_experience_rating, interface_rating (both 1–5)
Added: helpful_for_learning, avatar_relatable, would_recommend (yes / maybe / no)
Added: confusing_or_difficult, improvements, avatar_feedback (optional free text)
analytics.average_rating → five averages (average_session_rating, average_difficulty, average_clarity, average_overall_experience, average_interface)
Console item is flat (no comment rename — uses additional_info directly)
Removed: valuable_metric query parameter on the console list
Older rows in Mongo retain their original fields; reads gracefully return null for fields that weren’t part of the row’s submission. Submissions made after v2.2 follow the new shape. For the full current contract, see the current console feedbacks doc and the submit endpoint.