Fetch Canvas LMS Courses and Assignments

How to use

Assignment descriptions are truncated to 500 characters, and 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 hit the limits.

If you get 401 Unauthorized, the token is invalid or expired — regenerate it in Canvas Settings. For 403 Forbidden, the token lacks permission for that course. For an empty course list, try --enrollment-state active or omit the flag to see all states. If you see the wrong institution, verify that CANVAS_BASE_URL matches the URL in your browser; timeout errors mean you should check network connectivity to your Canvas instance.

1. Log in to your Canvas instance in a browser.
2. Go to Account → Settings (click your profile icon, then Settings).
3. Scroll to Approved Integrations and click + New Access Token.
4. Name the token (for example, “Hermes Agent”), set an optional expiry, and click Generate Token.
5. Copy the token and add it to ${HERMES_HOME:-~/.hermes}/.env.

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

Usage examples: list all active courses with --enrollment-state active, list all courses in any state, list assignments for a specific course ID, or order assignments by due date with --order-by due_at.

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

Output format: list_courses returns each course with its id, name, course_code, workflow_state, start_at, and end_at.

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

[{"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}]

API reference (curl): list courses with a Bearer-token GET to the courses endpoint, and list assignments for a course with a GET to that course's assignments endpoint, using parameters such as per_page, order_by, and enrollment_state.

# 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"

This skill is read-only — it only fetches data and never modifies courses or assignments.

On first use, verify auth by running $CANVAS list_courses — if it fails with 401, guide the user through setup.