Modules API

Modules are collections of learning materials useful for organizing courses and optionally providing a linear flow through them. Module items can be accessed linearly or sequentially depending on module configuration. Items can be unlocked by various criteria such as reading a page or achieving a minimum score on a quiz. Modules themselves can be unlocked by the completion of other Modules.

A Module object looks like:

{
  // the unique identifier for the module
  "id": 123,
  // the state of the module: 'active', 'deleted'
  "workflow_state": "active",
  // the position of this module in the course (1-based)
  "position": 2,
  // the name of this module
  "name": "Imaginary Numbers and You",
  // (Optional) the date this module will unlock
  "unlock_at": "2012-12-31T06:00:00-06:00",
  // Whether module items must be unlocked in order
  "require_sequential_progress": true,
  // IDs of Modules that must be completed before this one is unlocked
  "prerequisite_module_ids": [121, 122],
  // The number of items in the module
  "items_count": 10,
  // The API URL to retrive this module's items
  "items_url": "https://canvas.example.com/api/v1/modules/123/items",
  // The contents of this module, as an array of Module Items. (Present only if
  // requested via include[]=items AND the module is not deemed too large by
  // Canvas.)
  "items": null,
  // The state of this Module for the calling user one of 'locked', 'unlocked',
  // 'started', 'completed' (Optional; present only if the caller is a student or
  // if the optional parameter 'student_id' is included)
  "state": "started",
  // the date the calling user completed the module (Optional; present only if the
  // caller is a student or if the optional parameter 'student_id' is included)
  "completed_at": null,
  // if the student's final grade for the course should be published to the SIS
  // upon completion of this module
  "publish_final_grade": null,
  // (Optional) Whether this module is published. This field is present only if
  // the caller has permission to view unpublished modules.
  "published": true
}

A CompletionRequirement object looks like:

{
  // one of 'must_view', 'must_submit', 'must_contribute', 'min_score'
  "type": "min_score",
  // minimum score required to complete (only present when type == 'min_score')
  "min_score": 10,
  // whether the calling user has met this requirement (Optional; present only if
  // the caller is a student or if the optional parameter 'student_id' is
  // included)
  "completed": true
}

A ContentDetails object looks like:

{
  "points_possible": 20,
  "due_at": "2012-12-31T06:00:00-06:00",
  "unlock_at": "2012-12-31T06:00:00-06:00",
  "lock_at": "2012-12-31T06:00:00-06:00",
  "locked_for_user": true,
  "lock_explanation": "This quiz is part of an unpublished module and is not available yet.",
  "lock_info": {"asset_string":"assignment_4","unlock_at":"2012-12-31T06:00:00-06:00","lock_at":"2012-12-31T06:00:00-06:00","context_module":{}}
}

A ModuleItem object looks like:

{
  // the unique identifier for the module item
  "id": 768,
  // the id of the Module this item appears in
  "module_id": 123,
  // the position of this item in the module (1-based)
  "position": 1,
  // the title of this item
  "title": "Square Roots: Irrational numbers or boxy vegetables?",
  // 0-based indent level; module items may be indented to show a hierarchy
  "indent": 0,
  // the type of object referred to one of 'File', 'Page', 'Discussion',
  // 'Assignment', 'Quiz', 'SubHeader', 'ExternalUrl', 'ExternalTool'
  "type": "Assignment",
  // the id of the object referred to applies to 'File', 'Discussion',
  // 'Assignment', 'Quiz', 'ExternalTool' types
  "content_id": 1337,
  // link to the item in Canvas
  "html_url": "https://canvas.example.edu/courses/222/modules/items/768",
  // (Optional) link to the Canvas API object, if applicable
  "url": "https://canvas.example.edu/api/v1/courses/222/assignments/987",
  // (only for 'Page' type) unique locator for the linked wiki page
  "page_url": "my-page-title",
  // (only for 'ExternalUrl' and 'ExternalTool' types) external url that the item
  // points to
  "external_url": "https://www.example.com/externalurl",
  // (only for 'ExternalTool' type) whether the external tool opens in a new tab
  "new_tab": false,
  // Completion requirement for this module item
  "completion_requirement": {"type":"min_score","min_score":10,"completed":true},
  // (Present only if requested through include[]=content_details) If applicable,
  // returns additional details specific to the associated object
  "content_details": {"points_possible":20,"due_at":"2012-12-31T06:00:00-06:00","unlock_at":"2012-12-31T06:00:00-06:00","lock_at":"2012-12-31T06:00:00-06:00"},
  // (Optional) Whether this module item is published. This field is present only
  // if the caller has permission to view unpublished items.
  "published": true
}

A ModuleItemSequenceNode object looks like:

{
  // The previous ModuleItem in the sequence
  "prev": null,
  // The ModuleItem being queried
  "current": {"id":768,"module_id":123,"title":"A lonely page","type":"Page"},
  // The next ModuleItem in the sequence
  "next": {"id":769,"module_id":127,"title":"Project 1","type":"Assignment"},
  // The conditional release rule for the module item, if applicable
  "mastery_path": {"locked":true,"assignment_sets":[],"selected_set_id":null,"awaiting_choice":false,"still_processing":false,"modules_url":"\/courses\/11\/modules","choose_url":"\/courses\/11\/modules\/items\/9\/choose","modules_tab_disabled":false}
}

A ModuleItemSequence object looks like:

{
  // an array containing one ModuleItemSequenceNode for each appearence of the
  // asset in the module sequence (up to 10 total)
  "items": [{"prev":null,"current":{"id":768,"module_id":123,"title":"A lonely page","type":"Page"},"next":{"id":769,"module_id":127,"title":"Project 1","type":"Assignment"},"mastery_path":{"locked":true,"assignment_sets":[],"selected_set_id":null,"awaiting_choice":false,"still_processing":false,"modules_url":"\/courses\/11\/modules","choose_url":"\/courses\/11\/modules\/items\/9\/choose","modules_tab_disabled":false}}],
  // an array containing each Module referenced above
  "modules": [{"id":123,"name":"Overview"}, {"id":127,"name":"Imaginary Numbers"}]
}

List modules ContextModulesApiController#index

GET /api/v1/courses/:course_id/modules

Scope: url:GET|/api/v1/courses/:course_id/modules

A paginated list of the modules in a course

Request Parameters:

Parameter Type Description
include[] string
  • “items”: Return module items inline if possible. This parameter suggests that Canvas return module items directly in the Module object JSON, to avoid having to make separate API requests for each module when enumerating modules and items. Canvas is free to omit 'items' for any particular module if it deems them too numerous to return inline. Callers must be prepared to use the List Module Items API if items are not returned.

  • “content_details”: Requires 'items'. Returns additional details with module items specific to their associated content items. Includes standard lock information for each item.

Allowed values: items, content_details

search_term string

The partial name of the modules (and module items, if 'items' is specified with include[]) to match and return.

student_id string

Returns module completion information for the student with this id.

Example Request:

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/courses/222/modules
Returns a list of Modules

Show module ContextModulesApiController#show

GET /api/v1/courses/:course_id/modules/:id

Scope: url:GET|/api/v1/courses/:course_id/modules/:id

Get information about a single module

Request Parameters:

Parameter Type Description
include[] string
  • “items”: Return module items inline if possible. This parameter suggests that Canvas return module items directly in the Module object JSON, to avoid having to make separate API requests for each module when enumerating modules and items. Canvas is free to omit 'items' for any particular module if it deems them too numerous to return inline. Callers must be prepared to use the List Module Items API if items are not returned.

  • “content_details”: Requires 'items'. Returns additional details with module items specific to their associated content items. Includes standard lock information for each item.

Allowed values: items, content_details

student_id string

Returns module completion information for the student with this id.

Example Request:

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/courses/222/modules/123
Returns a Module

Create a module ContextModulesApiController#create

POST /api/v1/courses/:course_id/modules

Scope: url:POST|/api/v1/courses/:course_id/modules

Create and return a new module

Request Parameters:

Parameter Type Description
module[name] Required string

The name of the module

module[unlock_at] DateTime

The date the module will unlock

module[position] integer

The position of this module in the course (1-based)

module[require_sequential_progress] boolean

Whether module items must be unlocked in order

module[prerequisite_module_ids][] string

IDs of Modules that must be completed before this one is unlocked. Prerequisite modules must precede this module (i.e. have a lower position value), otherwise they will be ignored

module[publish_final_grade] boolean

Whether to publish the student's final grade for the course upon completion of this module.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules \
  -X POST \
  -H 'Authorization: Bearer <token>' \
  -d 'module[name]=module' \
  -d 'module[position]=2' \
  -d 'module[prerequisite_module_ids][]=121' \
  -d 'module[prerequisite_module_ids][]=122'
Returns a Module

Update a module ContextModulesApiController#update

PUT /api/v1/courses/:course_id/modules/:id

Scope: url:PUT|/api/v1/courses/:course_id/modules/:id

Update and return an existing module

Request Parameters:

Parameter Type Description
module[name] string

The name of the module

module[unlock_at] DateTime

The date the module will unlock

module[position] integer

The position of the module in the course (1-based)

module[require_sequential_progress] boolean

Whether module items must be unlocked in order

module[prerequisite_module_ids][] string

IDs of Modules that must be completed before this one is unlocked Prerequisite modules must precede this module (i.e. have a lower position value), otherwise they will be ignored

module[publish_final_grade] boolean

Whether to publish the student's final grade for the course upon completion of this module.

module[published] boolean

Whether the module is published and visible to students

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id> \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'module[name]=module' \
  -d 'module[position]=2' \
  -d 'module[prerequisite_module_ids][]=121' \
  -d 'module[prerequisite_module_ids][]=122'
Returns a Module

Delete module ContextModulesApiController#destroy

DELETE /api/v1/courses/:course_id/modules/:id

Scope: url:DELETE|/api/v1/courses/:course_id/modules/:id

Delete a module

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id> \
  -X Delete \
  -H 'Authorization: Bearer <token>'
Returns a Module

Re-lock module progressions ContextModulesApiController#relock

PUT /api/v1/courses/:course_id/modules/:id/relock

Scope: url:PUT|/api/v1/courses/:course_id/modules/:id/relock

Resets module progressions to their default locked state and recalculates them based on the current requirements.

Adding progression requirements to an active course will not lock students out of modules they have already unlocked unless this action is called.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id>/relock \
  -X PUT \
  -H 'Authorization: Bearer <token>'
Returns a Module

List module items ContextModuleItemsApiController#index

GET /api/v1/courses/:course_id/modules/:module_id/items

Scope: url:GET|/api/v1/courses/:course_id/modules/:module_id/items

A paginated list of the items in a module

Request Parameters:

Parameter Type Description
include[] string

If included, will return additional details specific to the content associated with each item. Refer to the Module Item specification for more details. Includes standard lock information for each item.

Allowed values: content_details

search_term string

The partial title of the items to match and return.

student_id string

Returns module completion information for the student with this id.

Example Request:

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/courses/222/modules/123/items
Returns a list of ModuleItems

Show module item ContextModuleItemsApiController#show

GET /api/v1/courses/:course_id/modules/:module_id/items/:id

Scope: url:GET|/api/v1/courses/:course_id/modules/:module_id/items/:id

Get information about a single module item

Request Parameters:

Parameter Type Description
include[] string

If included, will return additional details specific to the content associated with this item. Refer to the Module Item specification for more details. Includes standard lock information for each item.

Allowed values: content_details

student_id string

Returns module completion information for the student with this id.

Example Request:

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/courses/222/modules/123/items/768
Returns a ModuleItem

Create a module item ContextModuleItemsApiController#create

POST /api/v1/courses/:course_id/modules/:module_id/items

Scope: url:POST|/api/v1/courses/:course_id/modules/:module_id/items

Create and return a new module item

Request Parameters:

Parameter Type Description
module_item[title] string

The name of the module item and associated content

module_item[type] Required string

The type of content linked to the item

Allowed values: File, Page, Discussion, Assignment, Quiz, SubHeader, ExternalUrl, ExternalTool

module_item[content_id] Required string

The id of the content to link to the module item. Required, except for 'ExternalUrl', 'Page', and 'SubHeader' types.

module_item[position] integer

The position of this item in the module (1-based).

module_item[indent] integer

0-based indent level; module items may be indented to show a hierarchy

module_item[page_url] string

Suffix for the linked wiki page (e.g. 'front-page'). Required for 'Page' type.

module_item[external_url] string

External url that the item points to. [Required for 'ExternalUrl' and 'ExternalTool' types.

module_item[new_tab] boolean

Whether the external tool opens in a new tab. Only applies to 'ExternalTool' type.

module_item[completion_requirement][type] string

Completion requirement for this module item. “must_view”: Applies to all item types “must_contribute”: Only applies to “Assignment”, “Discussion”, and “Page” types “must_submit”, “min_score”: Only apply to “Assignment” and “Quiz” types Inapplicable types will be ignored

Allowed values: must_view, must_contribute, must_submit

module_item[completion_requirement][min_score] integer

Minimum score required to complete. Required for completion_requirement type 'min_score'.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id>/items \
  -X POST \
  -H 'Authorization: Bearer <token>' \
  -d 'module_item[title]=module item' \
  -d 'module_item[type]=ExternalTool' \
  -d 'module_item[content_id]=10' \
  -d 'module_item[position]=2' \
  -d 'module_item[indent]=1' \
  -d 'module_item[new_tab]=true'
Returns a ModuleItem

Update a module item ContextModuleItemsApiController#update

PUT /api/v1/courses/:course_id/modules/:module_id/items/:id

Scope: url:PUT|/api/v1/courses/:course_id/modules/:module_id/items/:id

Update and return an existing module item

Request Parameters:

Parameter Type Description
module_item[title] string

The name of the module item

module_item[position] integer

The position of this item in the module (1-based)

module_item[indent] integer

0-based indent level; module items may be indented to show a hierarchy

module_item[external_url] string

External url that the item points to. Only applies to 'ExternalUrl' type.

module_item[new_tab] boolean

Whether the external tool opens in a new tab. Only applies to 'ExternalTool' type.

module_item[completion_requirement][type] string

Completion requirement for this module item. “must_view”: Applies to all item types “must_contribute”: Only applies to “Assignment”, “Discussion”, and “Page” types “must_submit”, “min_score”: Only apply to “Assignment” and “Quiz” types Inapplicable types will be ignored

Allowed values: must_view, must_contribute, must_submit

module_item[completion_requirement][min_score] integer

Minimum score required to complete, Required for completion_requirement type 'min_score'.

module_item[published] boolean

Whether the module item is published and visible to students.

module_item[module_id] string

Move this item to another module by specifying the target module id here. The target module must be in the same course.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id>/items/<item_id> \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'module_item[position]=2' \
  -d 'module_item[indent]=1' \
  -d 'module_item[new_tab]=true'
Returns a ModuleItem

Select a mastery path ContextModuleItemsApiController#select_mastery_path

POST /api/v1/courses/:course_id/modules/:module_id/items/:id/select_mastery_path

Scope: url:POST|/api/v1/courses/:course_id/modules/:module_id/items/:id/select_mastery_path

Select a mastery path when module item includes several possible paths. Requires Mastery Paths feature to be enabled. Returns a compound document with the assignments included in the given path and any module items related to those assignments

Request Parameters:

Parameter Type Description
assignment_set_id string

Assignment set chosen, as specified in the mastery_paths portion of the context module item response

student_id string

Which student the selection applies to. If not specified, current user is implied.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id>/items/<item_id>/select_master_path \
  -X POST \
  -H 'Authorization: Bearer <token>' \
  -d 'assignment_set_id=2992'

Delete module item ContextModuleItemsApiController#destroy

DELETE /api/v1/courses/:course_id/modules/:module_id/items/:id

Scope: url:DELETE|/api/v1/courses/:course_id/modules/:module_id/items/:id

Delete a module item

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id>/items/<item_id> \
  -X Delete \
  -H 'Authorization: Bearer <token>'
Returns a ModuleItem

Mark module item as done/not done ContextModuleItemsApiController#mark_as_done

PUT /api/v1/courses/:course_id/modules/:module_id/items/:id/done

Scope: url:PUT|/api/v1/courses/:course_id/modules/:module_id/items/:id/done

Mark a module item as done/not done. Use HTTP method PUT to mark as done, and DELETE to mark as not done.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id>/items/<item_id>/done \
  -X Put \
  -H 'Authorization: Bearer <token>'

Get module item sequence ContextModuleItemsApiController#item_sequence

GET /api/v1/courses/:course_id/module_item_sequence

Scope: url:GET|/api/v1/courses/:course_id/module_item_sequence

Given an asset in a course, find the ModuleItem it belongs to, the previous and next Module Items in the course sequence, and also any applicable mastery path rules

Request Parameters:

Parameter Type Description
asset_type string

The type of asset to find module sequence information for. Use the ModuleItem if it is known (e.g., the user navigated from a module item), since this will avoid ambiguity if the asset appears more than once in the module sequence.

Allowed values: ModuleItem, File, Page, Discussion, Assignment, Quiz, ExternalTool

asset_id integer

The id of the asset (or the url in the case of a Page)

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/module_item_sequence?asset_type=Assignment&asset_id=123 \
  -H 'Authorization: Bearer <token>'
Returns a ModuleItemSequence

Mark module item read ContextModuleItemsApiController#mark_item_read

POST /api/v1/courses/:course_id/modules/:module_id/items/:id/mark_read

Scope: url:POST|/api/v1/courses/:course_id/modules/:module_id/items/:id/mark_read

Fulfills “must view” requirement for a module item. It is generally not necessary to do this explicitly, but it is provided for applications that need to access external content directly (bypassing the html_url redirect that normally allows Canvas to fulfill “must view” requirements).

This endpoint cannot be used to complete requirements on locked or unpublished module items.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id>/items/<item_id>/mark_read \
  -X POST \
  -H 'Authorization: Bearer <token>'