LTI ContextControls

Welcome to Our New API Docs! This is the new home for all things API (previously at Canvas LMS REST API Documentation).

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

Scope: 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

Scope: 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>"

Returns a Lti::ContextControl object.

Create LTI Context Control

Lti::ContextControlsController#create

POST /api/v1/accounts/:current_account_id/lti_registrations/:registration_id/controls

Scope: 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. true shows the tool in this context and all contexts below it. false disables the tool for this context and all contexts below it. Defaults to true.
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
         }'

Returns a Lti::ContextControl object.

Bulk Create LTI Context Controls

Lti::ContextControlsController#create_many

POST /api/v1/accounts/:account_id/lti_registrations/:registration_id/controls/bulk

Scope: 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. true shows the tool in this context and all contexts below it. false disables the tool for this context and all contexts below it. Defaults to true.

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 } \
             ]'

Returns a Lti::ContextControl object.

Modify a Context Control

Lti::ContextControlsController#update

PUT /api/v1/accounts/:account_id/lti_registrations/:registration_id/controls/:id

Scope: 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>"

Returns a Lti::ContextControl object.

Delete a Context Control

Lti::ContextControlsController#delete

DELETE /api/v1/accounts/:account_id/lti_registrations/:registration_id/controls/:id

Scope: 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>"

Returns a Lti::ContextControl object.

---

This documentation is generated directly from the Canvas LMS source code, available on Github.