External Tools API

API for accessing and configuring external tools on accounts and courses. "External tools" are IMS LTI links: http://www.imsglobal.org/developers/LTI/index.cfm

NOTE: Placements not documented here should be considered beta features and are not officially supported.

List external tools ExternalToolsController#index

GET /api/v1/courses/:course_id/external_tools

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

GET /api/v1/accounts/:account_id/external_tools

Scope: url:GET|/api/v1/accounts/:account_id/external_tools

GET /api/v1/groups/:group_id/external_tools

Scope: url:GET|/api/v1/groups/:group_id/external_tools

Returns the paginated list of external tools for the current context. See the get request docs for a single tool for a list of properties on an external tool.

Request Parameters:

Parameter Type Description
search_term string

The partial name of the tools to match and return.

selectable boolean

If true, then only tools that are meant to be selectable are returned.

include_parents boolean

If true, then include tools installed in all accounts above the current context

placement string

The placement type to filter by.

Example Request:

Return all tools at the current context as well as all tools from the parent, and filter the tools list to only those with a placement of 'editor_button'
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools?include_parents=true&placement=editor_button' \
     -H "Authorization: Bearer <token>"

Example Response:

[
 {
   "id": 1,
   "domain": "domain.example.com",
   "url": "http://www.example.com/ims/lti",
   "consumer_key": "key",
   "name": "LTI Tool",
   "description": "This is for cool things",
   "created_at": "2037-07-21T13:29:31Z",
   "updated_at": "2037-07-28T19:38:31Z",
   "privacy_level": "anonymous",
   "custom_fields": {"key": "value"},
   "is_rce_favorite": false,
   "is_top_nav_favorite": false,
   "account_navigation": {
        "canvas_icon_class": "icon-lti",
        "icon_url": "...",
        "text": "...",
        "url": "...",
        "label": "...",
        "selection_width": 50,
        "selection_height":50
   },
   "assignment_selection": null,
   "course_home_sub_navigation": null,
   "course_navigation": {
        "canvas_icon_class": "icon-lti",
        "icon_url": "...",
        "text": "...",
        "url": "...",
        "default": "disabled",
        "enabled": "true",
        "visibility": "public",
        "windowTarget": "_blank"
   },
   "editor_button": {
        "canvas_icon_class": "icon-lti",
        "icon_url": "...",
        "message_type": "ContentItemSelectionRequest",
        "text": "...",
        "url": "...",
        "label": "...",
        "selection_width": 50,
        "selection_height": 50
   },
   "homework_submission": null,
   "link_selection": null,
   "migration_selection": null,
   "resource_selection": null,
   "tool_configuration": null,
   "user_navigation": null,
   "selection_width": 500,
   "selection_height": 500,
   "icon_url": "...",
   "not_selectable": false,
   "deployment_id": null,
   "unified_tool_id": null
 },
 { ...  }
]

Get a sessionless launch url for an external tool. ExternalToolsController#generate_sessionless_launch

GET /api/v1/courses/:course_id/external_tools/sessionless_launch

Scope: url:GET|/api/v1/courses/:course_id/external_tools/sessionless_launch

GET /api/v1/accounts/:account_id/external_tools/sessionless_launch

Scope: url:GET|/api/v1/accounts/:account_id/external_tools/sessionless_launch

Returns a sessionless launch url for an external tool. Prefers the resource_link_lookup_uuid, but defaults to the other passed

parameters id, url, and launch_type

NOTE: Either the resource_link_lookup_uuid, id, or url must be provided unless launch_type is assessment or module_item.

Request Parameters:

Parameter Type Description
id string

The external id of the tool to launch.

url string

The LTI launch url for the external tool.

assignment_id string

The assignment id for an assignment launch. Required if launch_type is set to “assessment”.

module_item_id string

The assignment id for a module item launch. Required if launch_type is set to “module_item”.

launch_type string

The type of launch to perform on the external tool. Placement names (eg. “course_navigation”) can also be specified to use the custom launch url for that placement; if done, the tool id must be provided.

Allowed values: assessment, module_item

resource_link_lookup_uuid string

The identifier to lookup a resource link.

API response field:

  • id

    The id for the external tool to be launched.

  • name

    The name of the external tool to be launched.

  • url

    The url to load to launch the external tool for the user.

Example Request:

Finds the tool by id and returns a sessionless launch url
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'id=<external_tool_id>'

Finds the tool by launch url and returns a sessionless launch url
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'url=<lti launch url>'

Finds the tool associated with a specific assignment and returns a sessionless launch url
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'launch_type=assessment' \
     -F 'assignment_id=<assignment_id>'

Finds the tool associated with a specific module item and returns a sessionless launch url
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'launch_type=module_item' \
     -F 'module_item_id=<module_item_id>'

Finds the tool by id and returns a sessionless launch url for a specific placement
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'id=<external_tool_id>' \
     -F 'launch_type=<placement_name>'

Get a single external tool ExternalToolsController#show

GET /api/v1/courses/:course_id/external_tools/:external_tool_id

Scope: url:GET|/api/v1/courses/:course_id/external_tools/:external_tool_id

GET /api/v1/accounts/:account_id/external_tools/:external_tool_id

Scope: url:GET|/api/v1/accounts/:account_id/external_tools/:external_tool_id

Returns the specified external tool.

API response field:

  • id

    The unique identifier for the tool

  • domain

    The domain to match links against

  • url

    The url to match links against

  • consumer_key

    The consumer key used by the tool (The associated shared secret is not returned)

  • name

    The name of the tool

  • description

    A description of the tool

  • created_at

    Timestamp of creation

  • updated_at

    Timestamp of last update

  • privacy_level

    How much user information to send to the external tool: “anonymous”, “name_only”, “email_only”, “public”

  • custom_fields

    Custom fields that will be sent to the tool consumer

  • is_rce_favorite

    Boolean determining whether this tool should be in a preferred location in the RCE.

  • is_top_nav_favorite

    Boolean determining whether this tool should have a dedicated button in Top Navigation.

  • account_navigation

    The configuration for account navigation links (see create API for values)

  • assignment_selection

    The configuration for assignment selection links (see create API for values)

  • course_home_sub_navigation

    The configuration for course home navigation links (see create API for values)

  • course_navigation

    The configuration for course navigation links (see create API for values)

  • editor_button

    The configuration for a WYSIWYG editor button (see create API for values)

  • homework_submission

    The configuration for homework submission selection (see create API for values)

  • link_selection

    The configuration for link selection (see create API for values)

  • migration_selection

    The configuration for migration selection (see create API for values)

  • resource_selection

    The configuration for a resource selector in modules (see create API for values)

  • tool_configuration

    The configuration for a tool configuration link (see create API for values)

  • user_navigation

    The configuration for user navigation links (see create API for values)

  • selection_width

    The pixel width of the iFrame that the tool will be rendered in

  • selection_height

    The pixel height of the iFrame that the tool will be rendered in

  • icon_url

    The url for the tool icon

  • not_selectable

    whether the tool is not selectable from assignment and modules

  • unified_tool_id

    The unique identifier for the tool in LearnPlatform

  • deployment_id

    The unique identifier for the deployment of the tool

Example Response:

{
  "id": 1,
  "domain": "domain.example.com",
  "url": "http://www.example.com/ims/lti",
  "consumer_key": "key",
  "name": "LTI Tool",
  "description": "This is for cool things",
  "created_at": "2037-07-21T13:29:31Z",
  "updated_at": "2037-07-28T19:38:31Z",
  "privacy_level": "anonymous",
  "custom_fields": {"key": "value"},
  "account_navigation": {
       "canvas_icon_class": "icon-lti",
       "icon_url": "...",
       "text": "...",
       "url": "...",
       "label": "...",
       "selection_width": 50,
       "selection_height":50
  },
  "assignment_selection": null,
  "course_home_sub_navigation": null,
  "course_navigation": {
       "canvas_icon_class": "icon-lti",
       "icon_url": "...",
       "text": "...",
       "url": "...",
       "default": "disabled",
       "enabled": "true",
       "visibility": "public",
       "windowTarget": "_blank"
  },
  "editor_button": {
       "canvas_icon_class": "icon-lti",
       "icon_url": "...",
       "message_type": "ContentItemSelectionRequest",
       "text": "...",
       "url": "...",
       "label": "...",
       "selection_width": 50,
       "selection_height": 50
  },
  "homework_submission": null,
  "link_selection": null,
  "migration_selection": null,
  "resource_selection": null,
  "tool_configuration": null,
  "user_navigation": {
       "canvas_icon_class": "icon-lti",
       "icon_url": "...",
       "text": "...",
       "url": "...",
       "default": "disabled",
       "enabled": "true",
       "visibility": "public",
       "windowTarget": "_blank"
  },
  "selection_width": 500,
  "selection_height": 500,
  "icon_url": "...",
  "not_selectable": false
}

Create an external tool ExternalToolsController#create

POST /api/v1/courses/:course_id/external_tools

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

POST /api/v1/accounts/:account_id/external_tools

Scope: url:POST|/api/v1/accounts/:account_id/external_tools

Create an external tool in the specified course/account. The created tool will be returned, see the “show” endpoint for an example. If a client ID is supplied canvas will attempt to create a context external tool using the LTI 1.3 standard.

Request Parameters:

Parameter Type Description
client_id Required string

The client id is attached to the developer key. If supplied all other parameters are unnecessary and will be ignored

name Required string

The name of the tool

privacy_level Required string

How much user information to send to the external tool.

Allowed values: anonymous, name_only, email_only, public

consumer_key Required string

The consumer key for the external tool

shared_secret Required string

The shared secret with the external tool

description string

A description of the tool

url string

The url to match links against. Either “url” or “domain” should be set, not both.

domain string

The domain to match links against. Either “url” or “domain” should be set, not both.

icon_url string

The url of the icon to show for this tool

text string

The default text to show for this tool

custom_fields[field_name] string

Custom fields that will be sent to the tool consumer; can be used multiple times

is_rce_favorite boolean

(Deprecated in favor of Add tool to RCE Favorites and Remove tool from RCE Favorites) Whether this tool should appear in a preferred location in the RCE. This only applies to tools in root account contexts that have an editor button placement.

account_navigation[url] string

The url of the external tool for account navigation

account_navigation[enabled] boolean

Set this to enable this feature

account_navigation[text] string

The text that will show on the left-tab in the account navigation

account_navigation[selection_width] string

The width of the dialog the tool is launched in

account_navigation[selection_height] string

The height of the dialog the tool is launched in

account_navigation[display_type] string

The layout type to use when launching the tool. Must be “full_width”, “full_width_in_context”, “in_nav_context”, “borderless”, or “default”

user_navigation[url] string

The url of the external tool for user navigation

user_navigation[enabled] boolean

Set this to enable this feature

user_navigation[text] string

The text that will show on the left-tab in the user navigation

user_navigation[visibility] string

Who will see the navigation tab. “admins” for admins, “public” or “members” for everyone. Setting this to ‘null` will remove this configuration and use the default behavior, which is “public”.

Allowed values: admins, members, public

course_home_sub_navigation[url] string

The url of the external tool for right-side course home navigation menu

course_home_sub_navigation[enabled] boolean

Set this to enable this feature

course_home_sub_navigation[text] string

The text that will show on the right-side course home navigation menu

course_home_sub_navigation[icon_url] string

The url of the icon to show in the right-side course home navigation menu

course_navigation[enabled] boolean

Set this to enable this feature

course_navigation[text] string

The text that will show on the left-tab in the course navigation

course_navigation[visibility] string

Who will see the navigation tab. “admins” for course admins, “members” for students, “public” for everyone. Setting this to ‘null` will remove this configuration and use the default behavior, which is “public”.

Allowed values: admins, members, public

course_navigation[windowTarget] string

Determines how the navigation tab will be opened. “_blank” Launches the external tool in a new window or tab. “_self” (Default) Launches the external tool in an iframe inside of Canvas.

Allowed values: _blank, _self

course_navigation[default] string

If set to “disabled” the tool will not appear in the course navigation until a teacher explicitly enables it.

If set to “enabled” the tool will appear in the course navigation without requiring a teacher to explicitly enable it.

defaults to “enabled”

Allowed values: disabled, enabled

course_navigation[display_type] string

The layout type to use when launching the tool. Must be “full_width”, “full_width_in_context”, “in_nav_context”, “borderless”, or “default”

editor_button[url] string

The url of the external tool

editor_button[enabled] boolean

Set this to enable this feature

editor_button[icon_url] string

The url of the icon to show in the WYSIWYG editor

editor_button[selection_width] string

The width of the dialog the tool is launched in

editor_button[selection_height] string

The height of the dialog the tool is launched in

editor_button[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit

homework_submission[url] string

The url of the external tool

homework_submission[enabled] boolean

Set this to enable this feature

homework_submission[text] string

The text that will show on the homework submission tab

homework_submission[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit

link_selection[url] string

The url of the external tool

link_selection[enabled] boolean

Set this to enable this feature

link_selection[text] string

The text that will show for the link selection text

link_selection[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit

migration_selection[url] string

The url of the external tool

migration_selection[enabled] boolean

Set this to enable this feature

migration_selection[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit

tool_configuration[url] string

The url of the external tool

tool_configuration[enabled] boolean

Set this to enable this feature

tool_configuration[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit

tool_configuration[prefer_sis_email] boolean

Set this to default the lis_person_contact_email_primary to prefer provisioned sis_email; otherwise, omit

resource_selection[url] string

The url of the external tool

resource_selection[enabled] boolean

Set this to enable this feature. If set to false, not_selectable must also be set to true in order to hide this tool from the selection UI in modules and assignments.

resource_selection[icon_url] string

The url of the icon to show in the module external tool list

resource_selection[selection_width] string

The width of the dialog the tool is launched in

resource_selection[selection_height] string

The height of the dialog the tool is launched in

config_type string

Configuration can be passed in as CC xml instead of using query parameters. If this value is “by_url” or “by_xml” then an xml configuration will be expected in either the “config_xml” or “config_url” parameter. Note that the name parameter overrides the tool name provided in the xml

config_xml string

XML tool configuration, as specified in the CC xml specification. This is required if “config_type” is set to “by_xml”

config_url string

URL where the server can retrieve an XML tool configuration, as specified in the CC xml specification. This is required if “config_type” is set to “by_url”

not_selectable boolean

Default: false. If set to true, and if resource_selection is set to false, the tool won’t show up in the external tool selection UI in modules and assignments

oauth_compliant boolean

Default: false, if set to true LTI query params will not be copied to the post body.

unified_tool_id string

The unique identifier for the tool in LearnPlatform

Example Request:

This would create a tool on this course with two custom fields and a course navigation tab
curl -X POST 'https://<canvas>/api/v1/courses/<course_id>/external_tools' \
     -H "Authorization: Bearer <token>" \
     -F 'name=LTI Example' \
     -F 'consumer_key=asdfg' \
     -F 'shared_secret=lkjh' \
     -F 'url=https://example.com/ims/lti' \
     -F 'privacy_level=name_only' \
     -F 'custom_fields[key1]=value1' \
     -F 'custom_fields[key2]=value2' \
     -F 'course_navigation[text]=Course Materials' \
     -F 'course_navigation[enabled]=true'

This would create a tool on the account with navigation for the user profile page
curl -X POST 'https://<canvas>/api/v1/accounts/<account_id>/external_tools' \
     -H "Authorization: Bearer <token>" \
     -F 'name=LTI Example' \
     -F 'consumer_key=asdfg' \
     -F 'shared_secret=lkjh' \
     -F 'url=https://example.com/ims/lti' \
     -F 'privacy_level=name_only' \
     -F 'user_navigation[url]=https://example.com/ims/lti/user_endpoint' \
     -F 'user_navigation[text]=Something Cool'
     -F 'user_navigation[enabled]=true'

This would create a tool on the account with configuration pulled from an external URL
curl -X POST 'https://<canvas>/api/v1/accounts/<account_id>/external_tools' \
     -H "Authorization: Bearer <token>" \
     -F 'name=LTI Example' \
     -F 'consumer_key=asdfg' \
     -F 'shared_secret=lkjh' \
     -F 'config_type=by_url' \
     -F 'config_url=https://example.com/ims/lti/tool_config.xml'

Edit an external tool ExternalToolsController#update

PUT /api/v1/courses/:course_id/external_tools/:external_tool_id

Scope: url:PUT|/api/v1/courses/:course_id/external_tools/:external_tool_id

PUT /api/v1/accounts/:account_id/external_tools/:external_tool_id

Scope: url:PUT|/api/v1/accounts/:account_id/external_tools/:external_tool_id

Update the specified external tool. Uses same parameters as create

Example Request:

This would update the specified keys on this external tool
curl -X PUT 'https://<canvas>/api/v1/courses/<course_id>/external_tools/<external_tool_id>' \
     -H "Authorization: Bearer <token>" \
     -F 'name=Public Example' \
     -F 'privacy_level=public'

Delete an external tool ExternalToolsController#destroy

DELETE /api/v1/courses/:course_id/external_tools/:external_tool_id

Scope: url:DELETE|/api/v1/courses/:course_id/external_tools/:external_tool_id

DELETE /api/v1/accounts/:account_id/external_tools/:external_tool_id

Scope: url:DELETE|/api/v1/accounts/:account_id/external_tools/:external_tool_id

Remove the specified external tool

Example Request:

This would delete the specified external tool
curl -X DELETE 'https://<canvas>/api/v1/courses/<course_id>/external_tools/<external_tool_id>' \
     -H "Authorization: Bearer <token>"

Add tool to RCE Favorites ExternalToolsController#add_rce_favorite

POST /api/v1/accounts/:account_id/external_tools/rce_favorites/:id

Scope: url:POST|/api/v1/accounts/:account_id/external_tools/rce_favorites/:id

Add the specified editor_button external tool to a preferred location in the RCE for courses in the given account and its subaccounts (if the subaccounts haven’t set their own RCE Favorites). Cannot set more than 2 RCE Favorites.

Example Request:

curl -X POST 'https://<canvas>/api/v1/accounts/<account_id>/external_tools/rce_favorites/<id>' \
     -H "Authorization: Bearer <token>"

Remove tool from RCE Favorites ExternalToolsController#remove_rce_favorite

DELETE /api/v1/accounts/:account_id/external_tools/rce_favorites/:id

Scope: url:DELETE|/api/v1/accounts/:account_id/external_tools/rce_favorites/:id

Remove the specified external tool from a preferred location in the RCE for the given account

Example Request:

curl -X DELETE 'https://<canvas>/api/v1/accounts/<account_id>/external_tools/rce_favorites/<id>' \
     -H "Authorization: Bearer <token>"

Add tool to Top Navigation Favorites ExternalToolsController#add_top_nav_favorite

POST /api/v1/accounts/:account_id/external_tools/top_nav_favorites/:id

Scope: url:POST|/api/v1/accounts/:account_id/external_tools/top_nav_favorites/:id

Adds a dedicated button in Top Navigation for the specified tool for the given account. Cannot set more than 2 top_navigation Favorites.

Example Request:

curl -X POST 'https://<canvas>/api/v1/accounts/<account_id>/external_tools/top_nav_favorites/<id>' \
     -H "Authorization: Bearer <token>"

Remove tool from Top Navigation Favorites ExternalToolsController#remove_top_nav_favorite

DELETE /api/v1/accounts/:account_id/external_tools/top_nav_favorites/:id

Scope: url:DELETE|/api/v1/accounts/:account_id/external_tools/top_nav_favorites/:id

Removes the dedicated button in Top Navigation for the specified tool for the given account.

Example Request:

curl -X DELETE 'https://<canvas>/api/v1/accounts/<account_id>/external_tools/top_nav_favorites/<id>' \
     -H "Authorization: Bearer <token>"

Get visible course navigation tools ExternalToolsController#all_visible_nav_tools

GET /api/v1/external_tools/visible_course_nav_tools

Scope: url:GET|/api/v1/external_tools/visible_course_nav_tools

Get a list of external tools with the course_navigation placement that have not been hidden in course settings and whose visibility settings apply to the requesting user. These tools are the same that appear in the course navigation.

The response format is the same as for List external tools, but with additional context_id and context_name fields on each element in the array.

Request Parameters:

Parameter Type Description
context_codes[] Required string

List of context_codes to retrieve visible course nav tools for (for example, course_123). Only courses are presently supported.

API response field:

  • context_id

    The unique identifier of the associated context

  • context_name

    The name of the associated context

Example Request:

curl 'https://<canvas>/api/v1/external_tools/visible_course_nav_tools?context_codes[]=course_5' \
     -H "Authorization: Bearer <token>"

Example Response:

[{
  "id": 1,
  "domain": "domain.example.com",
  "url": "http://www.example.com/ims/lti",
  "context_id": 5,
  "context_name": "Example Course",
  ...
},
{ ...  }]

Get visible course navigation tools for a single course ExternalToolsController#visible_course_nav_tools

GET /api/v1/courses/:course_id/external_tools/visible_course_nav_tools

Scope: url:GET|/api/v1/courses/:course_id/external_tools/visible_course_nav_tools

Get a list of external tools with the course_navigation placement that have not been hidden in course settings and whose visibility settings apply to the requesting user. These tools are the same that appear in the course navigation.

The response format is the same as Get visible course navigation tools.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/visible_course_nav_tools' \
     -H "Authorization: Bearer <token>"