canvas-course-builder

Building Canvas courses via the API

Canvas has no "create a whole course" endpoint. A course is assembled from a dozen independent resources, each with its own publish state, and the API will happily let you build something that looks complete in the admin view and is entirely invisible to students. Most of the difficulty in this task is ordering, publish state, and idempotency — not the individual HTTP calls.

Before touching the API

Three things to establish first, because getting them wrong is expensive:

1. Which instance and whose token. Read CANVAS_API_URL (e.g. https://school.instructure.com) and CANVAS_API_TOKEN from the environment. Never put a token in a file you write, in a command line that lands in shell history, or in anything you show back to the user. If they paste a token into the conversation, use it from an env var you set and mention that they should rotate it afterwards.

2. Confirm identity and permissions before writing anything. GET /api/v1/users/self tells you who the token belongs to; GET /api/v1/accounts tells you which accounts they can create courses in (an empty list means teacher-level access — they can populate existing courses but not create new ones, which changes the whole plan). Do this even when the user seems certain, because a token scoped to the wrong sub-account fails halfway through a build and leaves debris.

3. Is this production? Creating course content is not reversible in a satisfying way — deleted objects linger, notifications fire, students see things. Ask which course or sub-account to build in, and prefer a sandbox sub-account or a test course for the first run. If the user is clearly iterating on a script, suggest they point it at a throwaway course first.

The build order that works

Dependencies run one direction. Follow this and you never have to backfill an ID:

1. Course shell            POST /accounts/:id/courses            (leave unpublished)
2. Sections                POST /courses/:id/sections
3. Assignment groups       POST /courses/:id/assignment_groups   (assignments need these)
4. Files                   3-step upload (see references/recipes.md)
5. Pages                   POST /courses/:id/pages
   Assignments             POST /courses/:id/assignments
   Discussions             POST /courses/:id/discussion_topics
   Quizzes + questions     POST /courses/:id/quizzes then .../questions
6. Modules                 POST /courses/:id/modules
7. Module items            POST /courses/:id/modules/:mid/items  (needs IDs from step 5)
8. Front page / syllabus   PUT  /courses/:id/front_page, PUT /courses/:id
9. Enrollments             POST /courses/:id/enrollments
10. Publish everything     modules → then the course itself