External Tools

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 ‘nullwill remove this configuration and use the default behavior, which is “public”.</p> 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 ‘nullwill remove this configuration and use the default behavior, which is “public”.</p> 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>"

---

© Instructure, Inc. Generated on Wed Nov 6 14:20:06 2024 This documentation is generated directly from the Canvas LMS source code, available on Github.