Community

Modules

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.

If any active AssignmentOverrides exist on a ContextModule, then only students who have an applicable override can access the module and are assigned its items. AssignmentOverrides can be created for a (group of) student(s) or a section.

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',
  // 'must_mark_done'
  "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"}]
}

A ModuleAssignmentOverride object looks like:

{
  // the ID of the assignment override
  "id": 4355,
  // the ID of the module the override applies to
  "context_module_id": 567,
  // the title of the override
  "title": "Section 6",
  // an array of the override's target students (present only if the override
  // targets an adhoc set of students)
  "students": null,
  // the override's target section (present only if the override targets a
  // section)
  "course_section": null
}

An OverrideTarget object looks like:

{
  // the ID of the user or section that the override is targeting
  "id": 7,
  // the name of the user or section that the override is targeting
  "name": "Section 6"
}

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 Module objects.

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 object.

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 object.

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 object.

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 object.

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 object.

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 ModuleItem objects.

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 object.

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 “must_mark_done”: Only applies to “Assignment” and “Page” types Inapplicable types will be ignored

Allowed values: must_view, must_contribute, must_submit, must_mark_done

module_item[completion_requirement][min_score]

integer

Minimum score required to complete. Required for completion_requirement type ‘min_score’.

module_item[iframe][width]

integer

Width of the ExternalTool on launch

module_item[iframe][height]

integer

Height of the ExternalTool on launch

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' \
  -d 'module_item[iframe][width]=300' \
  -d 'module_item[iframe][height]=200'

Returns a ModuleItem object.

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 “must_mark_done”: Only applies to “Assignment” and “Page” types Inapplicable types will be ignored

Allowed values: must_view, must_contribute, must_submit, must_mark_done

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 object.

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 object.

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 object.

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>'

List a module's overrides

ModuleAssignmentOverridesController#index

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

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

Returns a paginated list of AssignmentOverrides that apply to the ContextModule.

Example Request:

curl https://<canvas>/api/v1/courses/:course_id/modules/:context_module_id/assignment_overrides \
  -H 'Authorization: Bearer <token>'

Returns a list of ModuleAssignmentOverride objects.

Update a module's overrides

ModuleAssignmentOverridesController#bulk_update

PUT /api/v1/courses/:course_id/modules/:context_module_id/assignment_overrides

Scope: url:PUT|/api/v1/courses/:course_id/modules/:context_module_id/assignment_overrides

Accepts a list of overrides and applies them to the ContextModule. Returns 204 No Content response code if successful.

Request Parameters:

Parameter
Type
Description

overrides[]

Required Array

List of overrides to apply to the module. Overrides that already exist should include an ID and will be updated if needed. New overrides will be created for overrides in the list without an ID. Overrides not included in the list will be deleted. Providing an empty list will delete all of the module’s overrides. Keys for each override object can include: ‘id’, ‘title’, ‘student_ids’, and ‘course_section_id’.

Example Request:

curl https://<canvas>/api/v1/courses/:course_id/modules/:context_module_id/assignment_overrides \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "overrides": [
          {
            "id": 212,
            "course_section_id": 3564
          },
          {
            "title": "an assignment override",
            "student_ids": [1, 2, 3]
          }
        ]
      }'

This documentation is generated directly from the Canvas LMS source code, available on Github.

PreviousModerated GradingNextNames and Role

Last updated

Copyright © 2008-2024 Instructure, Inc. All rights reserved. Various trademarks held by their respective owners.