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 ModuleItemCompletionRequirement object looks like:

{
  
  "type": "min_score",
  
  "min_score": 10,
  
  "completed": "true"
}

A ModuleItemContentDetails 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"
}

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": "",
  
  //(Present only if requested through include[]=content_details) If applicable,
  //returns additional details specific to the associated object
  "content_details": ""
}

A ModuleItemSequenceAsset object looks like:

{
  
  "id": 768,
  
  "module_id": 123,
  
  "title": "A lonely page",
  
  "type": "Page"
}

A ModuleItemSequenceNode object looks like:

{
  
  "prev": "",
  
  "current": "",
  
  "next": ""
}

A ModuleItemSequence object looks like:

{
  
  //an array containing one hash for each appearence of the asset in the module
  //sequence (up to 10 total)
  "items": "",
  
  //an array containing each Module referenced above
  "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": "[]",
  
  //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": "",
  
  //if the student's final grade for the course should be published to the SIS upon
  //completion of this module
  "publish_final_grade": ""
}

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

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

A ModuleItemSequence object looks like:

{
  
  //an array containing one hash for each appearence of the asset in the module
  //sequence (up to 10 total)
  "items": "[{"prev"=>nil, "current"=>{"id"=>768, "module_id"=>123, "title"=>"A lonely page", "type"=>"Page"}, "next"=>{"id"=>769, "module_id"=>127, "title"=>"Project 1", "type"=>"Assignment"}}]",
  
  //an array containing each Module referenced above
  "modules": ""
}

List modules ContextModulesApiController#index

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

List the modules in a course

Request Parameters:

  • include[]
    String, "items"|"content_details"
    • "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 include. Returns additional details with module items specific to their associated content items.

  • search_term
    Optional, String

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

  • student_id
    Optional

    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

Get information about a single module

Request Parameters:

  • include[]
    String, "items"|"content_details"
    • "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 include. Returns additional details with module items specific to their associated content items.

  • student_id
    Optional

    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

Create and return a new module

Request Parameters:

  • module[name]
    String

    The name of the module

  • module[unlock_at]
    Optional, DateTime

    The date the module will unlock

  • module[position]
    Optional, Integer

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

  • module[require_sequential_progress]
    Optional, Boolean

    Whether module items must be unlocked in order

  • module[prerequisite_module_ids][]
    Optional, 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]
    Optional, 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

Update and return an existing module

Request Parameters:

  • module[name]
    Optional, String

    The name of the module

  • module[unlock_at]
    Optional, DateTime

    The date the module will unlock

  • module[position]
    Optional, Integer

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

  • module[require_sequential_progress]
    Optional, Boolean

    Whether module items must be unlocked in order

  • module[prerequisite_module_ids][]
    Optional, 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]
    Optional, Boolean

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

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

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[]
    String, "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, String

    The partial title of the items to match and return.

  • student_id
    Optional

    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

Get information about a single module item

Request Parameters:

  • include[]
    String, "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.

  • student_id
    Optional

    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

Create and return a new module item

Request Parameters:

  • module_item[title]
    Optional, String

    The name of the module item and associated content

  • module_item[type]
    String, "File"|"Page"|"Discussion"|"Assignment"|"Quiz"|"SubHeader"|"ExternalUrl"|"ExternalTool"

    The type of content linked to the item

  • module_item[content_id]
    String

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

  • module_item[position]
    Optional, Integer

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

  • module_item[indent]
    Optional, 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]
    Optional, Boolean

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

  • module_item[completion_requirement][type]
    Optional, String, "must_view"|"must_contribute"|"must_submit"

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

Update and return an existing module item

Request Parameters:

  • module_item[title]
    Optional, String

    The name of the module item

  • module_item[position]
    Optional, Integer

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

  • module_item[indent]
    Optional, Integer

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

  • module_item[external_url]
    Optional, String

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

  • module_item[new_tab]
    Optional, Boolean

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

  • module_item[completion_requirement][type]
    Optional, "must_view"|"must_contribute"|"must_submit"

    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]
    Integer

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

  • module_item[published]
    Optional, Boolean

    Whether the module item is published and visible to students.

  • module_item[module_id]
    Optional, 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[content_id]=10' \
  -d 'module_item[position]=2' \
  -d 'module_item[indent]=1' \
  -d 'module_item[new_tab]=true'
Returns a ModuleItem

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 ModuleItem

Get module item sequence ContextModuleItemsApiController#item_sequence

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

Given an asset in a course, find the ModuleItem it belongs to, and also the previous and next Module Items in the course sequence.

Request Parameters:

  • asset_type
    String, "ModuleItem"|"File"|"Page"|"Discussion"|"Assignment"|"Quiz"|"ExternalTool"

    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.

  • 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