Canvas LMS REST API Documentation

List external tools ExternalToolsController#index

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

GET /api/v1/accounts/:account_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.

Example Response:

[
 {
   "id":1,
   "name":"BLTI Example",
   "description":"This is for cool things"
   "url":"http://www.example.com/ims/lti",
   "domain":null,
   "privacy_level":anonymous
   "consumer_key":null,
   "created_at":"2037-07-21T13:29:31Z",
   "updated_at":"2037-07-28T19:38:31Z",
   "custom_fields":{"key":"value"},
   "account_navigation":{"url":"...", "text":"..."},
   "user_navigation":{"url":"...", "text":"..."},
   "course_navigation":{"url":"...", "text":"...", "visibility":"members", "default":true},
   "editor_button":{"url":"...", "text":"...", "selection_width":50, "selection_height":50, "icon_url":"..."},
   "resource_selection":{"url":"...", "text":"...", "selection_width":50, "selection_height":50}
 },
 {
   "id":2,
   "name":"Another BLTI Example",
   "description":"This one isn't very cool."
   "url":null,
   "domain":"example.com",
   "privacy_level":anonymous
   "consumer_key":null,
   "created_at":"2037-07-21T13:29:31Z",
   "updated_at":"2037-07-28T19:38:31Z"
 }
]

Get a single external tool ExternalToolsController#show

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

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
name

The name of the tool
description

A description of the tool
url

The url to match links against
domain

The domain to match links against
privacy_level

What information to send to the external tool, "anonymous", "name_only", "public"
consumer_key

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

Timestamp of creation
updated_at

Timestamp of last update
custom_fields

Custom fields that will be sent to the tool consumer
account_navigation

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

The configuration for user 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)
resource_selection

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

Example Response:

{
  "id":1,
  "name":"BLTI Example",
  "description":"This is for cool things"
  "url":"http://www.example.com/ims/lti",
  "domain":null,
  "privacy_level":anonymous
  "consumer_key":null,
  "created_at":"2037-07-21T13:29:31Z",
  "updated_at":"2037-07-28T19:38:31Z",
  "custom_fields":{"key":"value"},
  "account_navigation":{"url":"...", "text":"..."},
  "user_navigation":{"url":"...", "text":"..."},
  "course_navigation":{"url":"...", "text":"...", "visibility":"members", "default":true},
  "editor_button":{"url":"...", "selection_width":50, "selection_height":50, "icon_url":"..."},
  "resource_selection":{"url":"...", "selection_width":50, "selection_height":50}
}

Create an external tool ExternalToolsController#create

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

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.

Request Parameters:

name
string

The name of the tool
privacy_level
string

What information to send to the external tool, "anonymous", "name_only", "public"
consumer_key
string

The consumer key for the external tool
shared_secret
string

The shared secret with the external tool
description
string
optional

A description of the tool
url
string
optional

The url to match links against. Either "url" or "domain" should be set, not both.
domain
string
optional

The domain to match links against. Either "url" or "domain" should be set, not both.
icon_url
string
optional

The url of the icon to show for this tool
text
string
optional

The default text to show for this tool
custom_fields
string
optional

Custom fields that will be sent to the tool consumer, specified as custom_fields
account_navigation[url]
string
optional

The url of the external tool for account navigation
account_navigation[enabled]
boolean
optional

Set this to enable this feature
account_navigation[text]
string
optional

The text that will show on the left-tab in the account navigation
user_navigation[url]
string
optional

The url of the external tool for user navigation
user_navigation[enabled]
boolean
optional

Set this to enable this feature
user_navigation[text]
string
optional

The text that will show on the left-tab in the user navigation
course_navigation[url]
string
optional

The url of the external tool for course navigation
course_navigation[enabled]
boolean
optional

Set this to enable this feature
course_navigation[text]
string
optional

The text that will show on the left-tab in the course navigation
course_navigation[visibility]
string
optional

Who will see the navigation tab. "admins" for course admins, "members" for students, null for everyone
course_navigation[default]
boolean
optional

Whether the navigation option will show in the course by default or whether the teacher will have to explicitly enable it
editor_button[url]
string
optional

The url of the external tool
editor_button[enabled]
boolean
optional

Set this to enable this feature
editor_button[icon_url]
string
optional

The url of the icon to show in the WYSIWYG editor
editor_button[selection_width]
string
optional

The width of the dialog the tool is launched in
editor_button[selection_height]
string
optional

The height of the dialog the tool is launched in
resource_selection[url]
string
optional

The url of the external tool
resource_selection[enabled]
boolean
optional

Set this to enable this feature
resource_selection[icon_url]
string
optional

The url of the icon to show in the module external tool list
resource_selection[selection_width]
string
optional

The width of the dialog the tool is launched in
resource_selection[selection_height]
string
optional

The height of the dialog the tool is launched in
config_type
string
optional

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
optional

XML tool configuration, as specified in the CC xml specification. This is required if "config_type" is set to "by_xml"
config_url
string
optional

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"

Example Request:

This would create a tool on this course with two custom fields and a course navigation tab
curl 'http://<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[default]=false'
     -F 'course_navigation[enabled]=true'

This would create a tool on the account with navigation for the user profile page
curl 'http://<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 'http://<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

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 'http://<canvas>/api/v1/courses/<course_id>/external_tools/<external_tool_id>' \ 
     -H "Authorization: Bearer <token>" \ 
     -F 'name=Public Example' \ 
     -F 'privacy_level=public'

Canvas LMS - REST API and Extensions Documentation

External Tools API

List external tools ExternalToolsController#index

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

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

Example Response:

Get a single external tool ExternalToolsController#show

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

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

API response field:

Example Response:

Create an external tool ExternalToolsController#create

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

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

Request Parameters:

Example Request:

Edit an external tool ExternalToolsController#update

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

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

Example Request: