Comments
Comments are the questions and replies on the live course. These routes stay at /players/{id}/comments, /players/{id}/files/comment-counts, and /players/{playerId}/files/{fileId}/comments. In these pages a lesson is the curriculum item the HTTP paths call a file.
Overview
List Comments, List Comment Counts, and List Lesson Comments read the live course, not pending edits. They return no preview_url, draft_version, or draft_updated_at, and they do not send draft_version. Publish and unpublish do not change a comment. A lesson that exists only as a pending edit is 404. A lesson deleted as a pending edit, and still on the live course, can still appear here until you publish. See Draft, preview, and publish.
A question is a top-level comment. Each question includes every reply, oldest first. Replies are not a separate page. List Comments is the course inbox. List Lesson Comments is one lesson. List Comment Counts is one count per live lesson, including comments_count 0. A heading (type header) is omitted from the counts and is 404 as a lesson id. A hidden lesson on the live course is included.
When comments are turned off on the live course, all three routes return 200 with data: []. The two lists also return pagination with total 0 and total_pages 0. That is not an error. An unknown course, a heading, or a lesson that is not live is still 404 when comments are turned off.
has_solution=false is the unsolved queue. true is questions that have a marked solution. Omit has_solution for both. query is a case-insensitive substring of the question body only. An empty query is the same as omitting it. Reply text, the author name, and the lesson name are not searched.
A team member can call these routes without Manage courses or Publish courses. A caller who is not the workspace owner and not on that owner's team receives 403 FORBIDDEN.
A course id that is missing or not a UUID returns 404. {fileId} or file that is not a live lesson on that course returns 404. A file value that is not a UUID returns 422. See Identifiers.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /players/{id}/comments | List questions on the course |
| GET | /players/{id}/files/comment-counts | Count questions per lesson |
| GET | /players/{playerId}/files/{fileId}/comments | List questions on one lesson |
Question Object
Every field is present. List Comments also returns file_id and file_name. List Lesson Comments omits those two — the path already names the lesson.
| Field | Type | Description |
|---|---|---|
id | string | Comment UUID |
file_id | string | Lesson UUID from the files collection. Inbox only. |
file_name | string | Live lesson name. Inbox only. |
body | string | Question text, as typed |
created_at | string | ISO 8601 timestamp (UTC) |
author | object | Author Object |
likes_count | integer | Number of likes. 0 or greater. |
replies_count | integer | Number of replies on this question |
has_solution | boolean | true when a reply is marked as the solution |
replies | array | Every Reply Object, oldest first. Possibly empty. |
Author Object
Every field is present. avatar_url is null when there is no photo.
| Field | Type | Description |
|---|---|---|
name | string | Display name, then account name, then Student {n}, then Student |
initials | string | Initials of name |
avatar_url | string|null | Photo address, or null when there is no photo |
is_course_author | boolean | true when this person owns the course |
Reply Object
Every field is present. A reply has is_best_answer and does not include replies.
| Field | Type | Description |
|---|---|---|
id | string | Comment UUID |
body | string | Reply text, as typed |
created_at | string | ISO 8601 timestamp (UTC) |
author | object | Author Object |
likes_count | integer | Number of likes. 0 or greater. |
replies_count | integer | 0 |
is_best_answer | boolean | true when this reply is the marked solution |
Comment Count Object
List Comment Counts returns one of these per live lesson, lowest order first. A heading is omitted. comments_count 0 is included.
| Field | Type | Description |
|---|---|---|
file_id | string | Lesson UUID from the files collection |
comments_count | integer | Number of top-level questions on that lesson. 0 is included. |