We have relocated to Instructure Developer Documentation Portal. 🎉 Please update your bookmarks. This page will automatically redirect after July 1, 2026.
LTI ContextControls API
Configure the availability of an LTI Registration in a specific context. Used by the Canvas Apps page UI.
A Lti::ContextControl object looks like:
// Represent availability of an LTI registration in a specific context
{
// the Canvas ID of the Lti::ContextControl object
"id": 2,
// the Canvas ID of the Course that owns this. one of this or account_id will
// always be present
"course_id": 2,
// the Canvas ID of the Account that owns this. one of this or course_id will
// always be present
"account_id": 2,
// the Canvas ID of the ContextExternalTool that owns this, representing an LTI
// deployment
"deployment_id": 2,
// The state of this tool in this context. `true` means the tool is available in
// this context and in all contexts below it.
"available": true,
// A representation of the account hierarchy for the context that owns this
// object. Used for checking availability during LTI operations.
"path": "a1.a2.c3.",
// For UI display. Names of the accounts in the context's hierarchy. Excludes
// the root, and the current account if context is an account.
"display_path": ["Sub Account", "Other Account"],
// For UI display. The name of the context this object is associated with
"context_name": "My Course",
// For UI display. The depth of ContextControls for this particular deployment
// account chain, which can be different from the number of accounts in the
// chain.
"depth": 2,
// For UI display. The number of courses in this account and all nested
// subaccounts. 0 when context is a Course.
"course_count": 402,
// For UI display. The number of controls for accounts below this one, including
// all nested subaccounts. 0 when context is a Course.
"child_control_count": 42,
// For UI display. The number of subaccounts for this account. Includes all
// nested subaccounts. 0 when context is a Course.
"subaccount_count": 42,
// The state of the object
"workflow_state": "active",
// Timestamp of the object's creation
"created_at": "2024-01-01T00:00:00Z",
// Timestamp of the object's last update
"updated_at": "2024-01-01T00:00:00Z",
// The user that created this object. Not always present.
"created_by": {"type":"User"},
// The user that last updated this object. Not always present.
"updated_by": {"type":"User"}
}
List All Context Controls Lti::ContextControlsController#index
GET /api/v1/accounts/:account_id/lti_registrations/:registration_id/controls
url:GET|/api/v1/accounts/:account_id/lti_registrations/:registration_id/controls
List all LTI ContextControls for the given LTI Registration. These controls are partitioned by LTI Deployment, and have added calculated fields for display in the Canvas UI.
This endpoint is used to populate the Availability page for an LTI Registration and may not be useful for general API Usage. For listing all ContextControls for a given Deployment, see the LTI Deployments - List Controls for Deployment endpoint.
Example Request:
curl -X GET 'https://<canvas>/api/v1/accounts/<account_id>/lti_registrations/<registration_id>/controls' \
-H "Authorization: Bearer <token>"
Show LTI Context Control Lti::ContextControlsController#show
GET /api/v1/accounts/:account_id/lti_registrations/:registration_id/controls/:id
url:GET|/api/v1/accounts/:account_id/lti_registrations/:registration_id/controls/:id
Display details of the specified LTI ContextControl for the specified LTI registration in this context.
Example Request:
curl -X GET 'https://<canvas>/api/v1/accounts/<account_id>/lti_registrations/<registration_id>/controls/<control_id>' \
-H "Authorization: Bearer <token>"
Create LTI Context Control Lti::ContextControlsController#create
POST /api/v1/accounts/:current_account_id/lti_registrations/:registration_id/controls
url:POST|/api/v1/accounts/:current_account_id/lti_registrations/:registration_id/controls
Create a new LTI ContextControl for the specified LTI registration in this context.
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| account_id | integer |
The Canvas ID of the Account that owns this. One of account_id or course_id must be present. Can also be a string. |
|
| course_id | integer |
The Canvas ID of the Course that owns this. One of account_id or course_id must be present. Can also be a string. |
|
| deployment_id | integer |
The Canvas ID of the ContextExternalTool that owns this, representing an LTI deployment. If absent, this ContextControl will be associated with the Deployment of this Registration at the Root Account level. If that is not present, this request will fail. |
|
| available | boolean |
The state of this tool in this context. |
|
| comment | string |
A comment to add the to the change-log entry explaining why the changes were made. |
Example Request:
curl -X POST 'https://<canvas>/api/v1/accounts/<account_id>/lti_registrations/<registration_id>/controls' \
-H "Authorization: Bearer <token>" \
-d '{
"account_id": 1,
"deployment_id": 1,
"available": true
}'
Bulk Create LTI Context Controls Lti::ContextControlsController#create_many
POST /api/v1/accounts/:account_id/lti_registrations/:registration_id/controls/bulk
url:POST|/api/v1/accounts/:account_id/lti_registrations/:registration_id/controls/bulk
Create up to 100 new LTI ContextControls for the specified LTI registration in this context. Control parameters are sent as a JSON array of objects, each with the same parameters as the Create LTI Context Control endpoint. Note that if a control already exists for the specified context and deployment, it will be updated instead of created.
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| comment | string |
A comment to add the to the change-log entry explaining why the changes were made. |
|
| []account_id | integer |
The Canvas ID of the Account that owns this. One of account_id or course_id must be present. Can also be a string. |
|
| []course_id | integer |
The Canvas ID of the Course that owns this. One of account_id or course_id must be present. Can also be a string. |
|
| []deployment_id | integer |
The Canvas ID of the ContextExternalTool that owns this, representing an LTI deployment. If absent, this ContextControl will be associated with the Deployment of this Registration at the Root Account level. If that is not present, this request will fail. |
|
| []available | boolean |
The state of this tool in this context. |
Example Request:
curl -X POST 'https://<canvas>/api/v1/accounts/<account_id>/lti_registrations/<registration_id>/controls' \
-H "Authorization: Bearer <token>" \
--json '[ \
{ "account_id": 1, "available": false }, \
{ "course_id": 1, "deployment_id": 1 }, \
{ "account_id": 1, "deployment_id": 2 } \
]'
Modify a Context Control Lti::ContextControlsController#update
PUT /api/v1/accounts/:account_id/lti_registrations/:registration_id/controls/:id
url:PUT|/api/v1/accounts/:account_id/lti_registrations/:registration_id/controls/:id
Changes the availability of a context control. This endpoint can only be used to change the availability of a context control; no other attributes about the control (such as which course or account it belongs to) can be changed here. To change those values, the control should be deleted and a new one created instead.
Returns the context control with its new availability value applied.
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| available | Required | boolean |
the new value for this control’s availability |
| comment | string |
A comment to add the to the change-log entry explaining why the changes were made. |
Example Request:
curl "https://<canvas>/api/v1/accounts/<account_id>/lti_registrations/<registration_id>/controls/<id>" \
-X PUT \
-F "available=true" \
-H "Authorization: Bearer <token>"
Delete a Context Control Lti::ContextControlsController#delete
DELETE /api/v1/accounts/:account_id/lti_registrations/:registration_id/controls/:id
url:DELETE|/api/v1/accounts/:account_id/lti_registrations/:registration_id/controls/:id
Deletes a context control. Returns the control that is now deleted.
Note: Deleting the “primary” control for a deployment (the control associated with the context where the deployment is installed) is not allowed and will return an error. This prevents situations where a deployment cannot be managed from the Apps page.
Example Request:
curl "https://<canvas>/api/v1/accounts/<account_id>/lti_registrations/<registration_id>/controls/<id>" \
-X DELETE \
-H "Authorization: Bearer <token>"