Canvas LMS Read-Only API Reference

This document describes how to use the Hermes Canvas integration to read course and assignment data from Canvas LMS. The tool provides read-only access and is intended for listing courses, retrieving assignments, and verifying authentication.

Overview

The Canvas API tool connects to your institution's Canvas instance using a personal access token. It supports two primary operations: listing courses (optionally filtered by enrollment state) and listing assignments for a specific course (optionally ordered by due date). The tool automatically handles pagination via Link headers and returns data as JSON.

Prerequisites

Before using the tool, you need:

• A Canvas account with an API token generated.
• The environment variables CANVAS_API_TOKEN and CANVAS_BASE_URL set in the file ${HERMES_HOME:-~/.hermes}/.env.
• The Python script scripts/canvas_api.py available at $HERMES_HOME/skills/productivity/canvas/scripts/canvas_api.py.

Setup Canvas API Token

1. Log in to Canvas in a browser.
2. Navigate to Account → Settings (click the profile icon, then Settings).
3. Scroll to Approved Integrations and click + New Access Token.
4. Name the token (e.g., "Hermes Agent"), optionally set an expiry, and click Generate Token.
5. Copy the token.
6. Add the following lines to ${HERMES_HOME:-~/.hermes}/.env:

CANVAS_API_TOKEN=your_token_here
CANVAS_BASE_URL=https://yourschool.instructure.com

Replace your_token_here with the token you copied and https://yourschool.instructure.com with your institution's Canvas URL (no trailing slash).

Usage

Set the CANVAS variable to the script path:

CANVAS="python $HERMES_HOME/skills/productivity/canvas/scripts/canvas_api.py"

# List all active courses
$CANVAS list_courses --enrollment-state active

# List all courses (any state)
$CANVAS list_courses

# List assignments for a specific course
$CANVAS list_assignments 12345

# List assignments ordered by due date
$CANVAS list_assignments 12345 --order-by due_at

List Courses

• Command: $CANVAS list_courses
• Optional flag: --enrollment-state active to show only active enrollments.
• Output: JSON array with fields: id, name, course_code, workflow_state, start_at, end_at.

Example output:

[{"id": 12345, "name": "Intro to CS", "course_code": "CS101", "workflow_state": "available", "start_at": "...", "end_at": "..."}]

List Assignments for a Course

• Command: $CANVAS list_assignments COURSE_ID (replace COURSE_ID with the numeric course ID).
• Optional flag: --order-by due_at to order by due date.
• Output: JSON array with fields: id, name, due_at, points_possible, submission_types, html_url, description (truncated to 500 characters), course_id.

Example output:

[{"id": 67890, "name": "Homework 1", "due_at": "2025-02-15T23:59:00Z", "points_possible": 100, "submission_types": ["online_upload"], "html_url": "...", "description": "...", "course_id": 12345}]

Parameters

Parameter	Meaning	Required
CANVAS_API_TOKEN	Canvas API access token generated from Account Settings.	Yes
CANVAS_BASE_URL	Base URL of your Canvas instance (e.g., https://yourschool.instructure.com).	Yes
--enrollment-state	Filter courses by enrollment state (e.g., active).	No
--order-by	Order assignments by field (e.g., due_at).	No
COURSE_ID	Numeric ID of the course to list assignments for.	Yes (for list_assignments)

Constraints and Caveats

• Read-only: The tool only fetches data and never modifies courses or assignments.
• Assignment descriptions are truncated to 500 characters.
• The html_url field links to the full assignment page in Canvas.
• Canvas rate-limits to approximately 700 requests per 10 minutes. Check the X-Rate-Limit-Remaining header if you encounter limits.
• The Python script handles pagination automatically; raw curl does not.
• On first use, verify authentication by running $CANVAS list_courses. If you receive a 401 error, guide the user through the setup steps.

Failure Modes

Error	Cause	Resolution
401 Unauthorized	Token invalid or expired.	Regenerate the token in Canvas Settings.
403 Forbidden	Token lacks permission for this course.	Verify the token has appropriate scopes.
Empty course list	No courses match the filter.	Try --enrollment-state active or omit the flag to see all states.
Wrong institution	CANVAS_BASE_URL does not match the browser URL.	Verify CANVAS_BASE_URL matches your Canvas instance.
Timeout errors	Network connectivity issues.	Check connectivity to the Canvas instance.

Curl Equivalents

For troubleshooting or direct API access, you can use curl:

# List courses
curl -s -H "Authorization: Bearer $CANVAS_API_TOKEN" \
  "$CANVAS_BASE_URL/api/v1/courses?enrollment_state=active&per_page=10"

# List assignments for a course
curl -s -H "Authorization: Bearer $CANVAS_API_TOKEN" \
  "$CANVAS_BASE_URL/api/v1/courses/COURSE_ID/assignments?per_page=10&order_by=due_at"

Replace COURSE_ID with the numeric course ID. Note that curl does not automatically handle pagination.

Examples

• List active courses: $CANVAS list_courses --enrollment-state active
• List all courses: $CANVAS list_courses
• List assignments for course 12345: $CANVAS list_assignments 12345
• List assignments for course 12345 ordered by due date: $CANVAS list_assignments 12345 --order-by due_at

The year 2025 appears in the assignment due date example, showing a typical timestamp format used by Canvas.