list_discussion_topics and get_discussion_entries

The discussion tools give AI agents and CLI users direct access to Canvas discussion boards. Use list_discussion_topics to discover which discussions exist in a course, then pass a topic ID to get_discussion_entries to read the full thread with replies and participant metadata.

`list_discussion_topics`

Lists discussion topics in a course. The tool merges results from the Canvas discussions API and the assignments API so that graded discussions backed by assignments are always included. Announcements are excluded by default.

Parameters

course_id

string

required

The Canvas course ID. Obtain this from list_courses or resolve_course.

string

Substring filter applied to topic titles (or titles and message bodies when search_in is title_or_message). Case-insensitive. When exact_title is true, this value is compared as a case-folded exact match instead.

exact_title

boolean

When true, search is treated as a case-insensitive exact title match instead of a substring search. Has no effect when search is omitted.

search_in

string

default:"title"

Controls which fields the search substring is matched against. Accepted values: title (default) or title_or_message.

only_graded

boolean

When true, only topics that have an associated assignment_id (i.e., graded discussions) are returned.

include_announcements

boolean

default:"false"

When true, announcement topics are included alongside regular discussion topics. By default they are filtered out.

limit

integer

default:"100"

Maximum number of topics to return. Accepted range: 1–300.

search and exact_title interact: set exact_title: true to match "Week 1 Discussion" exactly, or omit it to match anything containing "week 1" in the title.

Return value

course_id

string

The course ID as provided.

count

integer

Number of topics returned after filtering.

filters

object

Echo of the active filter values: search, search_in, exact_title, only_graded, include_announcements.

topics

array

Show Topic object fields

string

Discussion topic ID.

id_aliases

array

Alternative ID representations for flexible lookup.

title

string

Topic title. Falls back to "Untitled discussion" when absent.

message

string

Opening message body of the topic (may be HTML).

posted_at

string

ISO 8601 timestamp when the topic was posted.

last_reply_at

string

ISO 8601 timestamp of the most recent reply.

discussion_type

string

Canvas discussion type, e.g. "side_comment" or "threaded".

is_announcement

boolean

true when the topic is an announcement.

published

boolean

Whether the topic is visible to students.

locked

boolean

Whether new replies are locked.

pinned

boolean

Whether the topic is pinned to the top of the board.

assignment_id

string

Present when the discussion is a graded assignment.

points_possible

number

Point value for graded discussions.

html_url

string

Direct Canvas URL to the discussion topic.

source

string

Indicates where the topic was sourced from: "discussion_topics_api" or "assignments_api".

Examples

# List all discussions in a course
canvas tool run list_discussion_topics --args '{"course_id": "12345"}'

# Search for topics containing "midterm" in the title
canvas tool run list_discussion_topics --args '{"course_id": "12345", "search": "midterm"}'

# Exact title match
canvas tool run list_discussion_topics --args '{"course_id": "12345", "search": "Week 3 Discussion", "exact_title": true}'

# List only graded discussions, up to 50
canvas tool run list_discussion_topics --args '{"course_id": "12345", "only_graded": true, "limit": 50}'

# Include announcements alongside discussions
canvas tool run list_discussion_topics --args '{"course_id": "12345", "include_announcements": true}'

Use the CLI shorthand for quick lookups:

canvas discussion show 12345 67890

`get_discussion_entries`

Fetches the full thread view for a single discussion topic, including top-level entries, nested replies, and participant metadata. The tool resolves the topic by ID or by assignment ID alias, so you can pass either a discussion topic ID or an assignment ID if the discussion is graded.

Parameters

course_id

string

required

The Canvas course ID.

topic_id

string

required

The discussion topic ID. Obtain this from list_discussion_topics. You may also pass an assignment ID for graded discussions — the tool resolves the linked topic automatically.

include_replies

boolean

default:"true"

When true (the default), nested replies are included under each top-level entry.

include_participants

boolean

default:"true"

When true (the default), a participants array is included with the display name, avatar URL, and pronoun fields for every user who posted in the thread.

limit

integer

default:"200"

Maximum number of top-level entries to return. Accepted range: 1–300. Replies nested under each entry are not counted against this limit.

If topic_id cannot be resolved to a valid discussion topic, the tool returns an error object with "error": "not_found". Always call list_discussion_topics first to retrieve a valid topic ID.

Return value

course_id

string

The course ID as provided.

requested_topic_id

string

The topic_id as supplied to the call.

resolved_topic_id

string

The canonical topic ID that Canvas returned entries for. May differ from requested_topic_id when an assignment ID was passed.

assignment_linked_topic_id

string

Set when an assignment ID was passed and the tool resolved it to a discussion topic ID.

topic

object

Show Topic summary fields

string

Topic ID.

title

string

Topic title.

message

string

Opening message body.

assignment_id

string

Assignment ID for graded discussions.

discussion_type

string

Canvas discussion type.

published

boolean

Whether the topic is published.

locked

boolean

Whether replies are locked.

html_url

string

Canvas URL for the topic.

participants_count

integer

Number of unique participants returned in the participants array.

participants

array

User objects with id, display_name, avatar_image_url, html_url, and pronouns. Only populated when include_participants is true.

top_level_entries_count

integer

Number of top-level entries in the entries array (after the limit is applied).

total_entries_count

integer

Total count including all nested replies across every entry.

entries

array

Top-level post objects. Each entry contains its author ID, message, created timestamp, and a replies array when include_replies is true.

Examples

# Fetch full thread for topic 67890 in course 12345
canvas tool run get_discussion_entries --args '{"course_id": "12345", "topic_id": "67890"}'

# Fetch without nested replies
canvas tool run get_discussion_entries --args '{"course_id": "12345", "topic_id": "67890", "include_replies": false}'

# Fetch without participant metadata
canvas tool run get_discussion_entries --args '{"course_id": "12345", "topic_id": "67890", "include_participants": false}'

# Limit to first 50 top-level entries
canvas tool run get_discussion_entries --args '{"course_id": "12345", "topic_id": "67890", "limit": 50}'

# CLI shorthand
canvas discussion show 12345 67890

Workflow: list then read

The typical pattern for reading a discussion thread:

List topics

Call list_discussion_topics to find the topic ID.

canvas tool run list_discussion_topics --args '{"course_id": "12345", "search": "Week 3"}'

Read entries

Pass the returned id to get_discussion_entries.

canvas tool run get_discussion_entries --args '{"course_id": "12345", "topic_id": "67890"}'

Core Tools

Content Tools

list_discussion_topics and get_discussion_entries