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

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

  // The state of this Module for the calling user
  // one of 'locked', 'unlocked', 'started', 'completed'
  // (Optional; present only if the caller is a student)
  state: 'started',

  // the date the calling user completed the module
  // (Optional; present only if the caller is a student)
  completed_at: nil
}

A Module Item object looks like:

{
  // the unique identifier for the module item
  id: 768,

  // 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: {
    // 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)
    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"
  }

}

List modules ContextModulesApiController#index

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

List the modules in a course

Request Parameters:

include[]
"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.
include[]
"content_details"

(Requires include) Returns additional details with module items specific to their associated content items.

Refer to the Module Item specification for more details.
search_term

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

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

Get information about a single module

Request Parameters:

include[]
"items"

Return module items inline if possible.

Please refer to the caveats outlined in the List modules endpoint.
include[]
"content_details"

If module items are included, also returns additional details specific to their associated content items.

Refer to the Module Item specification for more details.

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

Create and return a new module

Request Parameters:

module[name]
Required

The name of the module
module[unlock_at]
Optional

The date the module will unlock
module[position]
Optional

The position of this module in the course (1-based)
module[require_sequential_progress]
Optional

Whether module items must be unlocked in order
module[prerequisite_module_ids][]
Optional

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

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

Update and return an existing module

Request Parameters:

module[name]
Optional

The name of the module
module[unlock_at]
Optional

The date the module will unlock
module[position]
Optional

The position of the module in the course (1-based)
module[require_sequential_progress]
Optional

Whether module items must be unlocked in order
module[prerequisite_module_ids][]
Optional

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[published]
Optional

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

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

List module items ContextModuleItemsApiController#index

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

List the items in a module

Request Parameters:

include[]
"content_details"

If included, will return additional details specific to the content associated with each item.

Refer to the Module Item specification for more details.
search_term

(optional) The partial title of the items to match and return.

Example Request:

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

Returns a list of Module Items

Show module item ContextModuleItemsApiController#show

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

Get information about a single module item

Request Parameters:

include[]
"content_details"

If included, will return additional details specific to the content associated with this item.

Refer to the Module Item specification for more details.

Example Request:

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

Returns a Module Item

Create a module item ContextModuleItemsApiController#create

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

Create and return a new module item

Request Parameters:

module_item[title]
Optional

The name of the module item and associated content
module_item[type]
Required

The type of content linked to the item

one of "File", "Page", "Discussion", "Assignment", "Quiz", "SubHeader", "ExternalUrl", "ExternalTool"
module_item[content_id]
Required, except for 'ExternalUrl', 'Page', and 'SubHeader' types

The id of the content to link to the module item
module_item[position]
Optional

The position of this item in the module (1-based)
module_item[indent]
Optional

0-based indent level; module items may be indented to show a hierarchy
module_item[page_url]
Required for 'Page' type

Suffix for the linked wiki page (e.g. 'front-page')
module_item[external_url]
Required for 'ExternalUrl' and 'ExternalTool' types

External url that the item points to
module_item[new_tab]
Optional, only applies to 'ExternalTool' type

Whether the external tool opens in a new tab
module_item[completion_requirement][type]
Optional

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
module_item[completion_requirement][min_score]
Required for completion_requirement type 'min_score'

minimum score required to complete

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 Module Item

Update a module item ContextModuleItemsApiController#update

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

Update and return an existing module item

Request Parameters:

module_item[title]
Optional

The name of the module item
module_item[position]
Optional

The position of this item in the module (1-based)
module_item[indent]
Optional

0-based indent level; module items may be indented to show a hierarchy
module_item[external_url]
Optional, only applies to 'ExternalUrl' type

External url that the item points to
module_item[new_tab]
Optional, only applies to 'ExternalTool' type

Whether the external tool opens in a new tab
module_item[completion_requirement][type]
Optional

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
module_item[completion_requirement][min_score]
Required for completion_requirement type 'min_score'

minimum score required to complete
module_item[published]
Optional

Whether the module item is published and visible to students
module_item[module_id]
Optional

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[content_id]=10' \
  -d 'module_item[position]=2' \
  -d 'module_item[indent]=1' \
  -d 'module_item[new_tab]=true'

Returns a Module Item

Delete module item ContextModuleItemsApiController#destroy

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 Module Item