' . $url . '
' . $response . '
``` #### /login/oauth2/auth?code=\ At this point the app should notice that the URL of the webview has changed to contain `code=` somewhere in the query string. The app can then extract the code, and use it along with the client\_id and client\_secret to obtain the final access\_key. #### [Step 3: Exchange the code for the final access token](#oauth2-flow-3) [Back to Top](#top) To get a new access token and refresh token, send a [POST request to login/oauth2/token](/services/canvas/oauth2/file.oauth_endpoints#post-login-oauth2-token) with the following parameters: **Parameters** | Parameter | Value | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | grant\_type | authorization\_code | | client\_id | Your client\_id | | client\_secret | Your client\_secret | | redirect\_uri | If a redirect\_uri was passed to the initial request in step 1, the same redirect\_uri must be given here. | | code | code from canvas | | replace\_tokens | (optional) If this option is set to \`1\`, existing access tokens issued for this developer key/secret will be destroyed and replaced with the new token that is returned from this request | Note that the once the code issued in step 2 is used in a POST request to this endpoint, it is invalidated and further requests for tokens with the same code will fail. ### [Using an Access Token to authenticate requests](#using-access-tokens) [Back to Top](#top) Once you have an OAuth access token, you can use it to make API requests. If possible, using the HTTP Authorization header is recommended. OAuth2 Token sent in header: ```bash curl -H "Authorization: Bearer " "https://canvas.instructure.com/api/v1/courses" ``` Sending the access token in the query string or POST parameters is also supported, but discouraged as it increases the chances of the token being logged or leaked in transit. OAuth2 Token sent in query string: ```bash curl "https://canvas.instructure.com/api/v1/courses?access_token=" ``` ### [Using a Refresh Token to get a new Access Token](#using-refresh-tokens) [Back to Top](#top) Access tokens have a 1 hour lifespan. When the refresh flow is taken, Canvas will update the access token to a new value, reset the expiration timer, and return the new access token as part of the response. When refreshing tokens the user will not be asked to authorize the application again. To refresh the access token, send a [POST request to login/oauth2/token](/services/canvas/oauth2/file.oauth_endpoints#post-login-oauth2-token) with the following parameters: **Parameters** | Parameter | Value | | -------------- | ------------------------------------------------- | | grant\_type | refresh\_token | | client\_id | Your client\_id | | client\_secret | Your client\_secret | | refresh\_token | refresh\_token from initial access\_token request | The response to this request will not contain a new refresh token; the same refresh token is to be reused. ### [Logging Out](/services/canvas/oauth2/file.oauth_endpoints#delete-login-oauth2-token) [Back to Top](#top) To logout, simply send a [DELETE request to login/oauth2/token](/services/canvas/oauth2/file.oauth_endpoints#delete-login-oauth2-token) ## [Accessing LTI Advantage Services](#accessing-lti-advantage-services) [Back to Top](#top) LTI Advantage services, such as [Names and Role Provisioning Services](https://www.imsglobal.org/spec/lti-nrps/v2p0) and [Assignment and Grade Services](https://www.imsglobal.org/spec/lti-ags/v2p0/), require use of a client credentials grant flow for request authentication. This workflow is best summarized on the IMS Security Framework (specifically [Section 4](https://www.imsglobal.org/spec/security/v1p0/#using-oauth-2-0-client-credentials-grant)). Our goal here is to highlight some nuances that might help you access these services in Canvas, rather than describing the specification in detail. ### [Step 1: Developer Key Setup](#developer-key-setup) [Back to Top](#top) Before the client\_credentials grant flow can be achieved, an [LTI developer key must be created](https://community.canvaslms.com/t5/Admin-Guide/How-do-I-configure-an-LTI-key-for-an-account/ta-p/140). During developer key configuration, a public JWK can either be configured statically or can be dynamically rotated by providing JWKs by a URL that Canvas can reach. Tools may also use a previously issued client\_credentials token to [retroactively rotate the public JWK via an API request](/services/canvas/resources/public_jwk). The JWK must include an alg and use. **Example JWK** ``` "public_jwk": { "kty":"RSA", "alg":"RS256", "e":"AQAB", "kid":"8f796179-7ac4-48a3-a202-fc4f3d814fcd", "n":"nZA7QWcIwj-3N_RZ1qJjX6CdibU87y2l02yMay4KunambalP9g0fU9yILwLX9WYJINcXZDUf6QeZ-SSbblET-h8Q4OvfSQ7iuu0WqcvBGy8M0qoZ7I-NiChw8dyybMJHgpiP_AyxpCQnp3bQ6829kb3fopbb4cAkOilwVRBYPhRLboXma0cwcllJHPLvMp1oGa7Ad8osmmJhXhN9qdFFASg_OCQdPnYVzp8gOFeOGwlXfSFEgt5vgeU25E-ycUOREcnP7BnMUk7wpwYqlE537LWGOV5z_1Dqcqc9LmN-z4HmNV7b23QZW4_mzKIOY4IqjmnUGgLU9ycFj5YGDCts7Q", "use":"sig" } ``` ### [Step 2: Request an access token](#request-access-token) [Back to Top](#top) Once the developer key is configured and turned on, your tool can [request an LTI access token using the client\_credentials grant](/services/canvas/oauth2/file.oauth_endpoints#post-login-oauth2-token). This request must be signed by an RSA256 private key with a public key that is configured on the developer key as described in [Step 1: Developer Key Setup](#developer-key-setup). ### [Step 3: Use the access token to access LTI services](#use-access-token) [Back to Top](#top) Once you have an access token, you can use it to make LTI service requests. The access token must be included as a Bearer token in the Authorization header: ```bash curl -H "Authorization: Bearer " "https:///api/lti/courses/:course_id/names_and_roles" ``` Access tokens only work in the context of where a tool has been deployed. Tools can only access line items that are associated with their tool. The following endpoints are currently supported: #### Names and Role Provisioning Services * [Names and Role API](/services/canvas/resources/names_and_role) #### Assignment and Grade Services * [Line Items](/services/canvas/resources/line_items) * [Score](/services/canvas/resources/score) * [Result](/services/canvas/resources/result) *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # OAuth2 Endpoints {% hint style="warning" %} Developer keys issued after Oct 2015 generate tokens with a 1 hour expiration. Applications must use [refresh tokens](/services/canvas/oauth2/file.oauth#using-refresh-tokens) to generate new access tokens. {% endhint %} * [GET login/oauth2/auth](#get-login-oauth2-auth) * [POST login/oauth2/token](#post-login-oauth2-token) * [DELETE login/oauth2/token](#delete-login-oauth2-token) * [GET login/session\_token](#get-login-session-token) ## GET login/oauth2/auth ### GET https\://\/login/oauth2/auth?client\_id=XXX\&response\_type=code\&redirect\_uri=\%20\%20\ #### Parameters | Parameter | Required | Description | | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | client\_id | Required | The client id for your registered application. | | response\_type | Required | The type of OAuth2 response requested. The only currently supported value is `code`. | | redirect\_uri | Required | The URL where the user will be redirected after authorization. The domain of this URL must match the domain of the redirect\_uri stored on the developer key, or it must be a subdomain of that domain. For native applications, currently the only supported value is `urn:ietf:wg:oauth:2.0:oob`, signifying that the credentials will be retrieved out-of-band using an embedded browser or other functionality. | | state | Optional | Your application can pass Canvas an arbitrary piece of state in this parameter, which will be passed back to your application in Step 2. It's strongly encouraged that your application pass a unique identifier in the state parameter, and then verify in Step 2 that the state you receive back from Canvas is the same expected value. Failing to do this opens your application to the possibility of logging the wrong person in, as [described here](http://homakov.blogspot.com/2012/07/saferweb-most-common-oauth2.html). | | scope | Optional | This can be used to specify what information the Canvas API access token will provide access to. Canvas API scopes may be found beneath their corresponding endpoints in the "resources" documentation pages. If the developer key does not require scopes and no scope parameter is specified, the access token will have access to all scopes. If the developer key does require scopes and no scope parameter is specified, Canvas will respond with "invalid\_scope." To successfully pass multiple scope values, the scope parameter is included once, with multiple values separated by spaces. Passing multiple scope parameters, as is common in other areas of Canvas, causes only the last value to be applied to the generated token. | | purpose | Optional | This can be used to help the user identify which instance of an application this token is for. For example, a mobile device application could provide the name of the device. | | force\_login | Optional | Set to '1' if you want to force the user to enter their credentials, even if they're already logged into Canvas. By default, if a user already has an active Canvas web session, they will not be asked to re-enter their credentials. | | unique\_id | Optional | Set to the user's username to be populated in the login form in the event that the user must authenticate. | | prompt | Optional | If set to `none`, Canvas will immediately redirect to the `redirect_uri`. If the caller has a valid session with a "remember me" token or a token from a trusted Developer Key, the redirect will contain a `code=XYZ` param. If the caller has no session, the redirect will contain an `error=login_required` param. If the caller has a session, but no "remember me" or trusted token, the redirect will contain an `error=interaction_required` param. | ## POST login/oauth2/token See [Section 4.1.3](http://tools.ietf.org/html/rfc6749#section-4.1.3) of the OAuth2 RFC for more information about this process. ### POST /login/oauth2/token #### Parameters | Parameter | Required | Description | | ----------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | grant\_type | Required | Values currently supported: "authorization\_code", "refresh\_token", and "client\_credentials". | | client\_id | Required for grant\_types: authorization\_code, refresh\_token | The client id for your registered application. | | client\_secret | Required for grant\_types: authorization\_code, refresh\_token | The client secret for your registered application. | | redirect\_uri | Required for grant\_types: authorization\_code, refresh\_token | If a redirect\_uri was passed to the initial request in step 1, the same redirect\_uri must be given here. | | code | Required for grant\_type: authorization\_code | Required if grant\_type is authorization\_code. The code you received in a redirect response. | | refresh\_token | Required for grant\_type: refresh\_token | Required if grant\_type is refresh\_token. The refresh\_token you received in a redirect response. | | client\_assertion\_type | Required for grant\_type: client\_credentials | Currently the only supported value for this field is \`urn:ietf:params:oauth:client-assertion-type:jwt-bearer\`. | | client\_assertion | Required for grant\_type: client\_credentials | The signed jwt used to request an access token. Includes the value of Developer Key id as the sub claim of the jwt body. Should be signed by the private key of the stored public key on the DeveloperKey. | | scope | Required for grant\_type: client\_credentials | A list of scopes to be granted to the token. Currently only IMS defined scopes may be used. | #### Canvas API example responses For grant\_type of code or refresh\_token: | Parameter | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | access\_token | The OAuth2 Canvas API access token. | | token\_type | The type of token that is returned. | | user | A JSON object of canvas user id and user name. | | refresh\_token | The OAuth2 refresh token. | | expires\_in | Seconds until the access token expires. | | canvas\_region | For hosted Canvas, the AWS region (e.g. us-east-1) in which the institution that provided this token resides. For local or open source Canvas, this will have a value of "unknown". This field is safe to ignore. | When using grant\_type=code (ex: for Canvas API access): ``` { "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "token_type": "Bearer", "user": {"id":42, "name": "Jimi Hendrix"}, "refresh_token": "tIh2YBWGiC0GgGRglT9Ylwv2MnTvy8csfGyfK2PqZmkFYYqYZ0wui4tzI7uBwnN2", "expires_in": 3600, "canvas_region": "us-east-1" } ``` When using grant\_type=refresh\_token, the response will not contain a new refresh token since the same refresh token can be used multiple times: ``` { "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "token_type": "Bearer", "user": {"id":42, "name": "Jimi Hendrix"}, "expires_in": 3600 } ``` If scope=/auth/userinfo was specified in the [GET login/oauth2/auth](#get-login-oauth2-auth) request (ex: when using Canvas as an authentication service) then the response that results from [POST login/oauth2/token](#post-login-oauth2-token) would be: ``` { "access_token": null, "token_type": "Bearer", "user":{"id": 42, "name": "Jimi Hendrix"} } ``` #### Examples using client\_credentials When using grant\_type=client\_credentials (ex: [to access LTI Advantage Services](/services/canvas/oauth2/file.oauth#accessing-lti-advantage-services)): **Example request** This request must be signed by an RSA256 private key with a public key that is configured on the developer key as described in [Step 1: Developer Key Setup](/services/canvas/oauth2/file.oauth#developer-key-setup). ``` { "grant_type": "client_credentials", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "client_assertion": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjIwMTktMDYtMjFUMTQ6NTk6MzBaIn0.eyJpc3MiOiJodHRwczovL3d3dy5teS10b29sLmNvbSIsInN1YiI6Ilx1MDAzY2NsaWVudF9pZFx1MDAzZSIsImF1ZCI6Imh0dHA6Ly9cdTAwM2NjYW52YXNfZG9tYWluXHUwMDNlL2xvZ2luL29hdXRoMi90b2tlbiIsImlhdCI6MTU2MTc1MDAzMSwiZXhwIjoxNTYxNzUwNjMxLCJqdGkiOiJkZmZkYmRjZS1hOWYxLTQyN2ItOGZjYS02MDQxODIxOTg3ODMifQ.lUHCwDqx2ukKQ2vwoz_824IVcyq-rNdJKVpGUiJea5-Ybk_VfyKW5v0ky-4XTJrGHkDcj0T9J8qKfYbikqyetK44yXx1YGo-2Pn2GEZ26bZxCnuDUDhbqN8OZf4T8DnZsYP4OyhOseHERsHCzKF-SD2_Pk6ES5-Z8J55_aMyS3w3tl4nJtwsMm6FbMDp_FhSGE4xTwkBZ2KNM4JqkCwHGX_9KcpsPsHRFQjn9ysTeg-Qf7H2QFgFMFjsfQX-iSL_bQoC2npSz7rQ8awKMhCEYdMYZk2vVhQ7XQ8ysAyf3m1vlLbHjASpztcAB0lz_DJysT0Ep-Rh311Qf_vXHexjVA", "scope": "https://purl.imsglobal.org/spec/lti-ags/lineitem https://purl.imsglobal.org/spec/lti-ags/result/read" } ``` Below is an example of the decoded client\_assertion JWT in the above request: ``` //Header { "typ": "JWT", "alg": "RS256", "kid": "2019-06-21T14:59:30Z" } //Payload { "iss": "https://www.my-tool.com", "sub": "", "aud": "https:///login/oauth2/token", "iat": 1561750031, "exp": 1561750631, "jti": "dffdbdce-a9f1-427b-8fca-604182198783" } ``` NOTE: * the value of the sub claim should match the client\_id of the developer key in Canvas. * the value of the aud claim should contain either the domain of the Canvas account where the desired data resides, or the domain of the LTI 1.3 OIDC Auth endpoint, as described [here](/services/canvas/external-tools/lti/file.lti_launch_overview#step-2). * if the public key defined on the developer key is a JWK set (specified by an URL) the kid (key ID) value in the signed JWT header must match one of the public keys returned by the public key URL. **Example Response** | Parameter | Description | | ------------- | ------------------------------------------------------------------------- | | access\_token | The OAuth2 client\_credentials access token. | | token\_type | The type of token that is returned. | | expires\_in | Seconds until the access token expires. | | scope | The scope or space delimited list of scopes granted for the access token. | ``` { "access_token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ3d3cuZXhhbXBsZS5jb20iLCJpYXQiOiIxNDg1OTA3MjAwIiwiZXhwIjoiMTQ4NTkwNzUwMCIsImltc2dsb2JhbC5vcmcuc2VjdXJpdHkuc2NvcGUiOiJMdGlMaW5rU2V0dGluZ3MgU2NvcmUuaXRlbS5QVVQifQ.UWCuoD05KDYVQHEcciTV88YYtWWMwgb3sTbrjwxGBZA", "token_type" : "Bearer", "expires_in" : 3600, "scope" : "https://purl.imsglobal.org/spec/lti-ags/lineitem https://purl.imsglobal.org/spec/lti-ags/result/read" } ``` ## DELETE login/oauth2/token If your application supports logout functionality, you can revoke your own access token. This is useful for security reasons, as well as removing your application from the list of tokens on the user's profile page. Simply make an authenticated request to the following endpoint by including an Authorization header or providing the access\_token as a request parameter. ### DELETE /login/oauth2/token #### Parameters | Parameter | Required | Description | | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | expire\_sessions | Optional | Set this to '1' if you want to end all of the user's Canvas web sessions. Without this argument, the endpoint will leave web sessions intact.Additionally, if the user logged in to Canvas via a delegated authentication provider, and the provider supports Single Log Out functionality, the response will contain a forward\_url key. If you are still in control of the user's browsing session, it is recommended to then redirect them to this URL, in order to also log them out from where their session originated. Beware that it is unlikely that control will be returned to your application after this redirect. | #### Example responses ``` { "forward_url": "https://idp.school.edu/opaque_url" } ``` ## GET login/session\_token If your application needs to begin a normal web session in order to access features not supported via API (such as quiz taking), you can use your API access token in order to get a time-limited URL that can be fed to a browser or web view to begin a new web session. ### GET /login/session\_token #### Parameters | Parameter | Required | Description | | ---------- | -------- | ---------------------------------------------------------------------------------------------- | | return\_to | Optional | An optional URL to begin the web session at. Otherwise the user will be sent to the dashboard. | #### Example responses ``` { "session_url": "https://canvas.instructure.com/opaque_url" } ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Developer Keys Developer keys are OAuth2 client ID and secret pairs stored in Canvas that allow third-party applications to request access to Canvas API endpoints via the [OAuth2 flow](/services/canvas/oauth2/file.oauth). Access is granted after a user authorizes an app and Canvas creates an API access token that’s returned in the final request of the OAuth2 flow. Developer keys created in a root account, by root account administrators or Instructure employees, are only functional for the account they are created in and its sub-accounts. Developer keys created globally, by an Instructure employee, are functional in any Canvas account where they are enabled. By scoping the tokens, Canvas allows root account administrators to manage the specific API endpoints that tokens issued from a developer key have access to. ## Developer Key Scopes Developer key scopes allow root account administrators to restrict the tokens issued from developer keys to a subset of Canvas API endpoints in their account. Developer keys may be scoped or unscoped. Unscoped keys will have access to all Canvas resources available to the authorizing user. The following applies to scoped developer keys only: ### What are developer key scopes in Canvas? Each Canvas API endpoint has an associated scope. Canvas developer key scopes can only be enabled/disabled by a root account administrator or an Instructure employee. Scopes take the following form: ``` url:| ``` For example, the corresponding scope for the `GET /api/v1/courses/:course_id/rubrics` API endpoint would be ``` url:GET|/api/v1/courses/:course_id/rubrics ``` ### How do developer key scopes function? When requesting an access token, third-party applications should specify a `scope` parameter (see the [oauth endpoints documentation](/services/canvas/oauth2/file.oauth_endpoints#get-login-oauth2-auth)). The requested scopes must be a subset of the scopes set for the developer key. When a client makes any API request, Canvas will verify the requested endpoint's scope has been granted by the account administrator to the developer key of the request's access token. If the requested endpoint's scope has not been granted Canvas will respond with `401 Unauthorized`. ### Who can grant or revoke scopes for a developer key? For developer keys created in a specific root account, administrators for that account may grant or revoke scopes. When requesting a developer key, application owners should communicate with administrators which scopes their integrations require. For global developer keys, an Instructure employee may grant or revoke scopes. *Note:* If a scope is removed from a developer key, all access tokens derived from that key will be invalidated. In this case, clients should request a new access token. ### Where can I see what scopes are available? View the complete list of [token scopes](/services/canvas/resources/api_token_scopes). Scopes may also be found beneath their corresponding endpoints in the "resources" documentation pages. ### Configuring scopes on a developer key When creating or editing an API developer key, administrators can configure scopes in two ways: **Manual** - Browse and select scopes from a grouped list of all available Canvas API endpoints. **Paste Scopes** - Paste a list of scope strings directly into a text field. Scopes should be entered one per line or separated by spaces, using the format described above: ``` url:GET|/api/v1/courses/:course_id/rubrics url:POST|/api/v1/courses/:course_id/assignments ``` Any scope strings that are not recognized as valid Canvas API scopes will be flagged as invalid. The UI will display a warning listing the invalid scopes, and saving will be blocked until they are corrected or removed. ## Developer Key Management Developer key management features allow root account administrators to turn global developer keys "on" and "off" for only their account. ### What management features are available? Root account administrators may enable or disable global developer keys for their specific account. This means that vendors who wish to have integrations that work in any Canvas account may request a global developer key from Instructure allowing account administrators enable the key for their account. ### How do management features function? When a client uses the [OAuth2 Auth endpoint](/services/canvas/oauth2/file.oauth_endpoints#get-login-oauth2-auth) as part of the flow to retrieve an access token canvas will check the developer key associated with the `client_id`. If the developer key is not enabled in the requested account, Canvas will respond with `unauthorized_client`. When a client makes any API request, Canvas will check the developer key associated with the access token used in the request. If the developer key is not enabled for the requested account, Canvas will respond with `401 Unauthorized`. ## Other Considerations ### Maximum number of scopes When clients request an access token they may specify what scopes the token needs (see the [oauth endpoints documentation](/services/canvas/oauth2/file.oauth_endpoints#get-login-oauth2-auth)). Because the client sends the scopes they require in a GET request, the maximum number of scopes one access token can specify is limited by the maximum HTTP header size Canvas allows (8000 chars). On average, an access token may use up to 110 scopes. This number will vary depending on the actual length of the scopes used and any other headers sent in the [login oauth2 request](/services/canvas/oauth2/file.oauth_endpoints#get-login-oauth2-auth) along with the scopes. If the number of scopes required by the client exceeds this limitation, a second access token with the remaining scopes should be requested. ### Canvas API Includes Several Canvas APIs allow specifying an `include` parameter. This parameter allows nesting resources in JSON responses. For example, a request to the [assignment index endpoint](https://developerdocs.instructure.com/services/canvas/oauth2/pages/fmw03fjQMjjL5AFja2sQ#method.assignments_api.index) could be made to include the submission objects for each assignment. Responses to requests made with a scoped access token only support this functionality when the 'Allow Include Parameters' option is also enabled. When this option is disabled, a request is made with a scoped token Canvas will ignore `include` and `includes` parameters. ### Developer Key Scope Changes During the lifetime of a developer key, scopes may be added or removed by account administrators. Below is a description of possible changes and how each will affect access tokens: #### New scopes are added to a developer key Access tokens issued prior to the addition of the new scope will continue to function. These access tokens will not, however, be usable with the new scope. To access the newly added resources clients should request a new access token with scopes. The requested scopes must be a subset of the scopes on the developer key. #### Scopes are removed from a developer key Access tokens issued prior to the removal of the scope(s) will *not* continue to function. Clients should request a new access token with scopes. The requested scopes must be a subset of the scopes on the developer key. #### An unscoped developer key becomes scoped Access tokens issued prior to the change will *not* continue to function. Clients should request a new access token with scopes. The requested scopes must be a subset of the scopes on the developer key. If the client attempts to request a new access token without specifying scopes Canvas will respond with an error. For details on unscoped vs scoped developer key see `Developer Key Scopes` above. #### A scoped developer key becomes unscoped Access tokens issued prior to the change will continue to function *and* have access to all resources of the authorizing user. Clients may continue to request scoped access tokens, but these tokens will be functional for all resources available to the authorizing user. For details on unscoped vs scoped developer key see `Developer Key Scopes` above. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Resources # Access Tokens #### A Token object looks like: ```js { // The internal database ID of the token. "id": null, // The time the token was created. "created_at": null, // The time the token will permanently expire, or null if it does not // permanently expire. "expires_at": null, // The current state of the token. One of 'active', 'pending', 'disabled', or // 'deleted'. "workflow_state": null, // Whether the token should be remembered across sessions. Only applicable for // OAuth tokens. "remember_access": null, // The scopes associated with the token. If empty, there are no scope // limitations. "scopes": null, // If the token was created while masquerading, this is the ID of the real user. // Otherwise, null. "real_user_id": null, // The actual access token. Only included when the token is first created. "token": null, // A short, unique string that can be used to look up the token. "token_hint": null, // The ID of the user the token belongs to. "user_id": null, // The purpose of the token. "purpose": null, // If the token was created by an OAuth application, this is the name of that // application. Otherwise, null. "app_name": null, // Whether the current user can manually regenerate this token. "can_manually_regenerate": null } ``` ## [List access tokens for a user](#method.tokens.user_generated_tokens) [TokensController#user\_generated\_tokens](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `GET /api/v1/users/:user_id/user_generated_tokens` **Scope:** `url:GET|/api/v1/users/:user_id/user_generated_tokens` Returns a list of manually generated access tokens for the specified user. Note that the actual token values are only returned when the token is first created. #### Request Parameters: | Parameter | Type | Description | | ---------- | --------- | ------------------------------------------------------------------------- | | `per_page` | `integer` | The number of results to return per page. Defaults to 10. Maximum of 100. | Returns a list of [Token](#token) objects. ## [Show an access token](#method.tokens.show) [TokensController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `GET /api/v1/users/:user_id/tokens/:id` **Scope:** `url:GET|/api/v1/users/:user_id/tokens/:id` The ID can be the actual database ID of the token, or the 'token\_hint' value. ## [Create an access token](#method.tokens.create) [TokensController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `POST /api/v1/users/:user_id/tokens` **Scope:** `url:POST|/api/v1/users/:user_id/tokens` Create a new access token for the specified user. If the user is not the current user, the token will be created as "pending", and must be activated by the user before it can be used. #### Request Parameters: | Parameter | Type | Description | | ------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `token[purpose]` | Required `string` | The purpose of the token. | | `token[expires_at]` | `DateTime` | The time at which the token will expire. | | `token[scopes][]` | `Array` | The scopes to associate with the token.Ignored if the default developer key does not have the "enable scopes" option enabled.In such cases, the token will inherit the user's permissions instead. | ## [Update an access token](#method.tokens.update) [TokensController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `PUT /api/v1/users/:user_id/tokens/:id` **Scope:** `url:PUT|/api/v1/users/:user_id/tokens/:id` Update an existing access token. The ID can be the actual database ID of the token, or the 'token\_hint' value. Regenerating an expired token requires a new expiration date. #### Request Parameters: | Parameter | Type | Description | | ------------------- | ---------- | ---------------------------------------- | | `token[purpose]` | `string` | The purpose of the token. | | `token[expires_at]` | `DateTime` | The time at which the token will expire. | | `token[scopes][]` | `Array` | The scopes to associate with the token. | | `token[regenerate]` | `boolean` | Regenerate the actual token. | ## [Delete an access token](#method.tokens.destroy) [TokensController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `DELETE /api/v1/users/:user_id/tokens/:id` **Scope:** `url:DELETE|/api/v1/users/:user_id/tokens/:id` The ID can be the actual database ID of the token, or the 'token\_hint' value. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Accessibility Course Scans ## [Trigger accessibility course scan](#method.accessibility_course_scans.create) [AccessibilityCourseScansController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accessibility_course_scans_controller.rb) #### `POST /api/v1/users/:user_id/educator_accessibility_course_scan` **Scope:** `url:POST|/api/v1/users/:user_id/educator_accessibility_course_scan` Queues a background job that scans all a11y-enabled courses where the user has an active teacher or designer enrollment. Idempotent — if a scan is already queued or running, the existing Progress is returned. Requires the educator\_dashboard feature flag on the root account and a11y\_checker\_account\_statistics on site admin. #### Request Parameters: | Parameter | Type | Description | | --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | | `user_id` | Required `string` | The ID of the user, or "self" for the current user.The requesting user may only trigger a scan for themselves. | Returns a [Progress](/services/canvas/resources/progress#progress) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Accessibility Course Statistics #### An AccessibilityCourseStatistic object looks like: ```js // Per-course accessibility issue counts for a user's active teacher/designer // courses. { // The ID of the accessibility course statistic record "id": 1, // The ID of the course "course_id": 42, // The name of the course "course_name": "Introduction to Biology", // The course code (short name) of the course "course_code": "BIO101", // Whether the course is published "published": true, // The number of active accessibility issues in the course "active_issue_count": 5, // The number of resolved accessibility issues in the course "resolved_issue_count": 3, // The number of closed accessibility issues in the course "closed_issue_count": 2, // The workflow state of the statistic record "workflow_state": "active", // The date and time the record was created "created_at": "2026-01-01T00:00:00Z", // The date and time the record was last updated "updated_at": "2026-01-02T00:00:00Z" } ``` ## [List accessibility course statistics](#method.accessibility_course_statistics.index) [AccessibilityCourseStatisticsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accessibility_course_statistics_controller.rb) #### `GET /api/v1/users/:user_id/educator_accessibility_course_statistics` **Scope:** `url:GET|/api/v1/users/:user_id/educator_accessibility_course_statistics` Returns per-course accessibility issue statistics for the current user's active teacher and designer courses. Only courses where the accessibility checker is enabled and whose workflow state is neither completed nor deleted are included. Only statistic records with workflow\_state "active" are returned. Requires the educator\_dashboard feature flag to be enabled on the root account, and a11y\_checker\_account\_statistics on site admin plus a11y\_checker on the account (i.e. a11y\_checker\_account\_statistics? must be true). #### Request Parameters: | Parameter | Type | Description | | -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | Required `string` | The ID of the user, or "self" for the current user.The requesting user may only retrieve their own statistics. | | `enrollment_term_id` | `string` | When present, only include courses that belong to the given enrollmentterm(s). Accepts a single term id or an array(enrollment\_term\_id\[]=1\&enrollment\_term\_id\[]=2), and each value may be aterm id or SIS term id. Returns 404 if any given term does not exist inthis account. | Returns a list of [AccessibilityCourseStatistic](#accessibilitycoursestatistic) objects. ## [List accessibility course statistic terms](#method.accessibility_course_statistics.terms) [AccessibilityCourseStatisticsController#terms](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accessibility_course_statistics_controller.rb) #### `GET /api/v1/users/:user_id/educator_accessibility_course_terms` **Scope:** `url:GET|/api/v1/users/:user_id/educator_accessibility_course_terms` Returns the distinct enrollment terms that the current user's active teacher and designer courses belong to -- the same courses reported by the List accessibility course statistics endpoint. Use this to populate a term filter for that endpoint. There is no "all terms" entry; "all terms" is represented by omitting the enrollment\_term\_id filter. Requires the same account settings and feature flags as the statistics endpoint. #### Request Parameters: | Parameter | Type | Description | | --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- | | `user_id` | Required `string` | The ID of the user, or "self" for the current user.The requesting user may only retrieve their own terms. | Returns a list of [EnrollmentTerm](/services/canvas/resources/enrollment_terms#enrollmentterm) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Account Calendars API for viewing and toggling settings of account calendars. An account calendar is available for each account in Canvas. All account calendars are hidden by default, but administrators with the `manage_account_calendar_visibility` permission may set calendars as visible. Administrators with the `manage_account_calendar_events` permission can create events in visible account calendars, and users associated with an account can add the calendar and see its events (if the calendar is visible). Events on calendars set as `auto_subscribe` calendars will appear on users' calendars even if they do not manually add it. #### An AccountCalendar object looks like: ```js { // the ID of the account associated with this calendar "id": 204, // the name of the account associated with this calendar "name": "Department of Chemistry", // the account's parent ID, or null if this is the root account "parent_account_id": 1, // the ID of the root account, or null if this is the root account "root_account_id": 1, // whether this calendar is visible to users "visible": true, // whether users see this calendar's events without needing to manually add it "auto_subscribe": false, // number of this account's direct sub-accounts "sub_account_count": 0, // Asset string of the account "asset_string": "account_4", // Object type "type": "account", // url to get full detailed events "calendar_event_url": "/accounts/2/calendar_events/%7B%7B%20id%20%7D%7D", // whether the user can create calendar events "can_create_calendar_events": true, // API path to create events for the account "create_calendar_event_url": "/accounts/2/calendar_events", // url to open the more options event editor "new_calendar_event_url": "/accounts/6/calendar_events/new" } ``` ## [List available account calendars](#method.account_calendars_api.index) [AccountCalendarsApiController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `GET /api/v1/account_calendars` **Scope:** `url:GET|/api/v1/account_calendars` Returns a paginated list of account calendars available to the current user. Includes visible account calendars where the user has an account association. #### Request Parameters: | Parameter | Type | Description | | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `search_term` | `string` | When included, searches available account calendars for the term. Returns matchingresults. Term must be at least 2 characters. | #### Example Request: ```bash curl https:///api/v1/account_calendars \ -H 'Authorization: Bearer ' ``` Returns a list of [AccountCalendar](#accountcalendar) objects. ## [Get a single account calendar](#method.account_calendars_api.show) [AccountCalendarsApiController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `GET /api/v1/account_calendars/:account_id` **Scope:** `url:GET|/api/v1/account_calendars/:account_id` Get details about a specific account calendar. #### Example Request: ```bash curl https:///api/v1/account_calendars/204 \ -H 'Authorization: Bearer ' ``` Returns an [AccountCalendar](#accountcalendar) object. ## [Update a calendar](#method.account_calendars_api.update) [AccountCalendarsApiController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `PUT /api/v1/account_calendars/:account_id` **Scope:** `url:PUT|/api/v1/account_calendars/:account_id` Set an account calendar's visibility and auto\_subscribe values. Requires the `manage_account_calendar_visibility` permission on the account. #### Request Parameters: | Parameter | Type | Description | | ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `visible` | `boolean` | Allow administrators with manage\_account\_calendar\_events permissionto create events on this calendar, and allow users to view thiscalendar and its events. | | `auto_subscribe` | `boolean` | When true, users will automatically see events from this account in theircalendar, even if they haven't manually added that calendar. | #### Example Request: ```bash curl https:///api/v1/account_calendars/204 \ -X PUT \ -H 'Authorization: Bearer ' \ -d 'visible=false' \ -d 'auto_subscribe=false' ``` Returns an [AccountCalendar](#accountcalendar) object. ## [Update several calendars](#method.account_calendars_api.bulk_update) [AccountCalendarsApiController#bulk\_update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `PUT /api/v1/accounts/:account_id/account_calendars` **Scope:** `url:PUT|/api/v1/accounts/:account_id/account_calendars` Set visibility and/or auto\_subscribe on many calendars simultaneously. Requires the `manage_account_calendar_visibility` permission on the account. Accepts a JSON array of objects containing 2-3 keys each: `id` (the account's id, required), `visible` (a boolean indicating whether the account calendar is visible), and `auto_subscribe` (a boolean indicating whether users should see these events in their calendar without manually subscribing). Returns the count of updated accounts. #### Example Request: ```bash curl https:///api/v1/accounts/1/account_calendars \ -X PUT \ -H 'Authorization: Bearer ' \ --data '[{"id": 1, "visible": true, "auto_subscribe": false}, {"id": 13, "visible": false, "auto_subscribe": true}]' ``` ## [List all account calendars](#method.account_calendars_api.all_calendars) [AccountCalendarsApiController#all\_calendars](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `GET /api/v1/accounts/:account_id/account_calendars` **Scope:** `url:GET|/api/v1/accounts/:account_id/account_calendars` Returns a paginated list of account calendars for the provided account and its first level of sub-accounts. Includes hidden calendars in the response. Requires the `manage_account_calendar_visibility` permission. #### Request Parameters: | Parameter | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search_term` | `string` | When included, searches all descendent accounts of provided account for theterm. Returns matching results. Term must be at least 2 characters. Can becombined with a filter value. | | `filter` | `string` | When included, only returns calendars that are either visible or hidden. Canbe combined with a search term. Allowed values: visible, hidden | #### Example Request: ```bash curl https:///api/v1/accounts/1/account_calendars \ -H 'Authorization: Bearer ' ``` Returns a list of [AccountCalendar](#accountcalendar) objects. ## [Count of all visible account calendars](#method.account_calendars_api.visible_calendars_count) [AccountCalendarsApiController#visible\_calendars\_count](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `GET /api/v1/accounts/:account_id/visible_calendars_count` **Scope:** `url:GET|/api/v1/accounts/:account_id/visible_calendars_count` Returns the number of visible account calendars. #### Example Request: ```bash curl https:///api/v1/accounts/1/visible_calendars_count \ -H 'Authorization: Bearer ' ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Account Domain Lookups ## [Search account domains](#method.account_domain_lookups.search) #### `GET /api/v1/accounts/search` **Scope:** `url:GET|/api/v1/accounts/search` Returns a list of up to 5 matching account domains Partial match on name / domain are supported #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | -------------- | | `name` | `string` | campus name | | `domain` | `string` | no description | | `latitude` | `number` | no description | | `longitude` | `number` | no description | #### Example Request: ```bash curl https:///api/v1/accounts/search \ -G -H 'Authorization: Bearer ' \ -d 'name=utah' ``` #### Example Response: ```js [ { "name": "University of Utah", "domain": "utah.edu", "distance": null, // distance is always nil, but preserved in the api response for backwards compatibility "authentication_provider": "canvas", // which authentication_provider param to pass to the oauth flow; may be NULL }, ... ] ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Account Notifications API for account notifications. #### An AccountNotification object looks like: ```js { // The subject of the notifications "subject": "Attention Students", // The message to be sent in the notification. "message": "This is a test of the notification system.", // When to send out the notification. "start_at": "2013-08-28T23:59:00-06:00", // When to expire the notification. "end_at": "2013-08-29T23:59:00-06:00", // The icon to display with the message. Defaults to warning. "icon": "information", // (Deprecated) The roles to send the notification to. If roles is not passed // it defaults to all roles "roles": ["StudentEnrollment"], // The roles to send the notification to. If roles is not passed it defaults to // all roles "role_ids": [1], // The author of the notification. Available only to admins using include_all. "author": {"id":1,"name":"John Doe"} } ``` ## [Index of active global notification for the user](#method.account_notifications.user_index) [AccountNotificationsController#user\_index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `GET /api/v1/accounts/:account_id/account_notifications` **Scope:** `url:GET|/api/v1/accounts/:account_id/account_notifications` Returns a list of all global notifications in the account for the current user Any notifications that have been closed by the user will not be returned, unless a include\_past parameter is passed in as true. Admins can request all global notifications for the account by passing in an include\_all parameter. #### Request Parameters: | Parameter | Type | Description | | ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------- | | `include_past` | `boolean` | Include past and dismissed global announcements. | | `include_all` | `boolean` | Include all global announcements, regardless of user's role or availability date. Only available to account admins. | | `show_is_closed` | `boolean` | Include a flag for each notification indicating whether it has been read by the user. | #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/users/self/account_notifications ``` Returns a list of [AccountNotification](#accountnotification) objects. ## [Show a global notification](#method.account_notifications.show) [AccountNotificationsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `GET /api/v1/accounts/:account_id/account_notifications/:id` **Scope:** `url:GET|/api/v1/accounts/:account_id/account_notifications/:id` Returns a global notification for the current user A notification that has been closed by the user will not be returned #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/users/self/account_notifications/4 ``` Returns an [AccountNotification](#accountnotification) object. ## [Create a global notification](#method.account_notifications.create) [AccountNotificationsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `POST /api/v1/accounts/:account_id/account_notifications` **Scope:** `url:POST|/api/v1/accounts/:account_id/account_notifications` Create and return a new global notification for an account. #### Request Parameters: | Parameter | Type | Description | | -------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_notification[subject]` | Required `string` | The subject of the notification. | | `account_notification[message]` | Required `string` | The message body of the notification. | | `account_notification[start_at]` | Required `DateTime` | The start date and time of the notification in ISO8601 format.e.g. 2014-01-01T01:00Z | | `account_notification[end_at]` | Required `DateTime` | The end date and time of the notification in ISO8601 format.e.g. 2014-01-01T01:00Z | | `account_notification[icon]` | `string` | The icon to display with the notification.Note: Defaults to warning. Allowed values: warning, information, question, error, calendar | | `account_notification_roles[]` | `string` | The role(s) to send global notification to. Note: ommitting this field will send to everyoneExample:account\_notification\_roles: \["StudentEnrollment", "TeacherEnrollment"] | #### Example Request: ```bash curl -X POST -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/account_notifications \ -d 'account_notification[subject]=New notification' \ -d 'account_notification[start_at]=2014-01-01T00:00:00Z' \ -d 'account_notification[end_at]=2014-02-01T00:00:00Z' \ -d 'account_notification[message]=This is a global notification' ``` #### Example Response: ```js { "subject": "New notification", "start_at": "2014-01-01T00:00:00Z", "end_at": "2014-02-01T00:00:00Z", "message": "This is a global notification" } ``` ## [Update a global notification](#method.account_notifications.update) [AccountNotificationsController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `PUT /api/v1/accounts/:account_id/account_notifications/:id` **Scope:** `url:PUT|/api/v1/accounts/:account_id/account_notifications/:id` Update global notification for an account. #### Request Parameters: | Parameter | Type | Description | | -------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_notification[subject]` | `string` | The subject of the notification. | | `account_notification[message]` | `string` | The message body of the notification. | | `account_notification[start_at]` | `DateTime` | The start date and time of the notification in ISO8601 format.e.g. 2014-01-01T01:00Z | | `account_notification[end_at]` | `DateTime` | The end date and time of the notification in ISO8601 format.e.g. 2014-01-01T01:00Z | | `account_notification[icon]` | `string` | The icon to display with the notification. Allowed values: `warning`, `information`, `question`, `error`, `calendar` | | `account_notification_roles[]` | `string` | The role(s) to send global notification to. Note: ommitting this field will send to everyoneExample:account\_notification\_roles: \["StudentEnrollment", "TeacherEnrollment"] | #### Example Request: ```bash curl -X PUT -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/account_notifications/1 \ -d 'account_notification[subject]=New notification' \ -d 'account_notification[start_at]=2014-01-01T00:00:00Z' \ -d 'account_notification[end_at]=2014-02-01T00:00:00Z' \ -d 'account_notification[message]=This is a global notification' ``` #### Example Response: ```js { "subject": "New notification", "start_at": "2014-01-01T00:00:00Z", "end_at": "2014-02-01T00:00:00Z", "message": "This is a global notification" } ``` ## [Close notification for user. Destroy notification for admin](#method.account_notifications.user_close_notification) [AccountNotificationsController#user\_close\_notification](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `DELETE /api/v1/accounts/:account_id/account_notifications/:id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/account_notifications/:id` If the current user no longer wants to see this account notification, it can be closed with this call. This affects the current user only. If the current user is an admin and they pass a remove parameter with a value of "true", the account notification will be destroyed. This affects all users. #### Request Parameters: | Parameter | Type | Description | | --------- | --------- | --------------------------------- | | `remove` | `boolean` | Destroy the account notification. | #### Example Request: ```bash curl -X DELETE -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/account_notifications/4 ``` Returns an [AccountNotification](#accountnotification) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Account Reports API for accessing account reports. #### A Report object looks like: ```js { // The unique identifier for the report. "id": 1, // The type of report. "report": "sis_export_csv", // The url to the report download. "file_url": "https://example.com/some/path", // The attachment api object of the report. Only available after the report has // completed. "attachment": null, // The status of the report "status": "complete", // The date and time the report was created. "created_at": "2013-12-01T23:59:00-06:00", // The date and time the report started processing. "started_at": "2013-12-02T00:03:21-06:00", // The date and time the report finished processing. "ended_at": "2013-12-02T00:03:21-06:00", // The time (in seconds) the report has been waiting to run, has been running so // far, or took to run to completion, depending on its current state. "run_time": 33.3, // The report parameters "parameters": {"course_id":2,"start_at":"2012-07-13T10:55:20-06:00","end_at":"2012-07-13T10:55:20-06:00"}, // The progress of the report "progress": 100, // This is the current line count being written to the report. It updates every // 1000 records. "current_line": 12000, // The user that initiated the account report. See the Users API for details. "user": null } ``` #### A ReportParameters object looks like: ```js // The parameters returned will vary for each report. { // The canvas id of the term to get grades from "enrollment_term_id": 2, // If true, deleted objects will be included. If false, deleted objects will be // omitted. "include_deleted": false, // The id of the course to report on "course_id": 2, // The sort order for the csv, Options: 'users', 'courses', 'outcomes'. "order": "users", // If true, user data will be included. If false, user data will be omitted. "users": false, // If true, account data will be included. If false, account data will be // omitted. "accounts": false, // If true, term data will be included. If false, term data will be omitted. "terms": false, // If true, course data will be included. If false, course data will be omitted. "courses": false, // If true, section data will be included. If false, section data will be // omitted. "sections": false, // If true, enrollment data will be included. If false, enrollment data will be // omitted. "enrollments": false, // If true, group data will be included. If false, group data will be omitted. "groups": false, // If true, data for crosslisted courses will be included. If false, data for // crosslisted courses will be omitted. "xlist": false, "sis_terms_csv": 1, "sis_accounts_csv": 1, // If true, enrollment state will be included. If false, enrollment state will // be omitted. Defaults to false. "include_enrollment_state": false, // Include enrollment state. Defaults to 'all' Options: ['active'| 'invited'| // 'creation_pending'| 'deleted'| 'rejected'| 'completed'| 'inactive'| 'all'] "enrollment_state": ["all"], // The beginning date for submissions. Max time range is 2 weeks. "start_at": "2012-07-13T10:55:20-06:00", // The end date for submissions. Max time range is 2 weeks. "end_at": "2012-07-13T10:55:20-06:00" } ``` ## [List Available Reports](#method.account_reports.available_reports) [AccountReportsController#available\_reports](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `GET /api/v1/accounts/:account_id/reports` **Scope:** `url:GET|/api/v1/accounts/:account_id/reports` Returns a paginated list of reports for the current context. #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Array of additional information to include."description\_html":: an HTML description of the report, with example output"parameters\_html":: an HTML form for the report parameters Allowed values: description\_html, params\_html | #### API response field: * name The name of the report. * parameters The parameters will vary for each report * last\_run \[Report] The last run of the report. This will be null if the report has never been run. #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts//reports/ ``` #### Example Response: ```js [ { "report":"student_assignment_outcome_map_csv", "title":"Student Competency", "parameters":null, "last_run": { "id": 1, "report": "student_assignment_outcome_map_csv", "file_url": "https://example.com/some/path", "status": "complete", "created_at": "2013-12-01T23:59:00-06:00", "started_at": "2013-12-02T00:03:21-06:00", "ended_at": "2013-12-02T00:03:21-06:00" }, { "report":"grade_export_csv", "title":"Grade Export", "parameters":{ "term":{ "description":"The canvas id of the term to get grades from", "required":true } }, "last_run": null } ] ``` ## [Start a Report](#method.account_reports.create) [AccountReportsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `POST /api/v1/accounts/:account_id/reports/:report` **Scope:** `url:POST|/api/v1/accounts/:account_id/reports/:report` Generates a report instance for the account. Note that "report" in the request must match one of the available report names. To fetch a list of available report names and parameters for each report (including whether or not those parameters are required), see [List Available Reports](#method.account_reports.available_reports). #### Request Parameters: | Parameter | Type | Description | | -------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `parameters[]` | `Hash` | The parameters will vary for each report. To fetch a listof available parameters for each report, see List Available Reports.A few example parameters have been provided below. Note that the exampleparameters provided below may not be valid for every report. | | `parameters[skip_message]` | `boolean` | If true, no message will be sentto the user upon completion of the report. | | `parameters[course_id]` | `integer` | The id of the course to report on.Note: this parameter has been listed to serve as an example and may not bevalid for every report. | | `parameters[users]` | `boolean` | If true, user data will be included. Iffalse, user data will be omitted. Note: this parameter has been listed toserve as an example and may not be valid for every report. | #### Example Request: ```bash curl -X POST \ https:///api/v1/accounts/1/reports/provisioning_csv \ -H 'Authorization: Bearer ' \ -H 'Content-Type: multipart/form-data' \ -F 'parameters[users]=true' \ -F 'parameters[courses]=true' \ -F 'parameters[enrollments]=true' ``` Returns a [Report](/services/canvas/resources/course_reports#report) object. ## [Index of Reports](#method.account_reports.index) [AccountReportsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `GET /api/v1/accounts/:account_id/reports/:report` **Scope:** `url:GET|/api/v1/accounts/:account_id/reports/:report` Shows all reports that have been run for the account of a specific type. #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts//reports/ ``` Returns a list of [Report](/services/canvas/resources/course_reports#report) objects. ## [Status of a Report](#method.account_reports.show) [AccountReportsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `GET /api/v1/accounts/:account_id/reports/:report/:id` **Scope:** `url:GET|/api/v1/accounts/:account_id/reports/:report/:id` Returns the status of a report. #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts//reports// ``` Returns a [Report](/services/canvas/resources/course_reports#report) object. ## [Delete a Report](#method.account_reports.destroy) [AccountReportsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `DELETE /api/v1/accounts/:account_id/reports/:report/:id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/reports/:report/:id` Deletes a generated report instance. #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ -X DELETE \ https:///api/v1/accounts//reports// ``` Returns a [Report](/services/canvas/resources/course_reports#report) object. ## [Abort a Report](#method.account_reports.abort) [AccountReportsController#abort](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `PUT /api/v1/accounts/:account_id/reports/:report/:id/abort` **Scope:** `url:PUT|/api/v1/accounts/:account_id/reports/:report/:id/abort` Abort a report in progress #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ -X PUT \ https:///api/v1/accounts//reports///abort ``` Returns a [Report](/services/canvas/resources/course_reports#report) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Accounts API for accessing account data. #### An Account object looks like: ```js { // the ID of the Account object "id": 2, // The display name of the account "name": "Canvas Account", // The UUID of the account "uuid": "WvAHhY5FINzq5IyRIJybGeiXyFkG3SqHUPb7jZY5", // The account's parent ID, or null if this is the root account "parent_account_id": 1, // The ID of the root account, or null if this is the root account "root_account_id": 1, // The storage quota for the account in megabytes, if not otherwise specified "default_storage_quota_mb": 500, // The storage quota for a user in the account in megabytes, if not otherwise // specified "default_user_storage_quota_mb": 50, // The storage quota for a group in the account in megabytes, if not otherwise // specified "default_group_storage_quota_mb": 50, // The default time zone of the account. Allowed time zones are // {http://www.iana.org/time-zones IANA time zones} or friendlier // {http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html Ruby on Rails // time zones}. "default_time_zone": "America/Denver", // The friendly Ruby on Rails name of the account's default time zone. Since // several Rails time zones can share a single IANA identifier (the value // returned in default_time_zone), this field disambiguates which one is // configured. "default_time_zone_friendly_name": "Mountain Time (US & Canada)", // The account's identifier in the Student Information System. Only included if // the user has permission to view SIS information. "sis_account_id": "123xyz", // The account's identifier in the Student Information System. Only included if // the user has permission to view SIS information. "integration_id": "123xyz", // The id of the SIS import if created through SIS. Only included if the user // has permission to manage SIS information. "sis_import_id": 12, // The number of courses directly under the account (available via include) "course_count": 10, // The number of sub-accounts directly under the account (available via include) "sub_account_count": 10, // The account's identifier that is sent as context_id in LTI launches. "lti_guid": "123xyz", // The state of the account. Can be 'active' or 'deleted'. "workflow_state": "active" } ``` #### A TermsOfService object looks like: ```js { // Terms Of Service id "id": 1, // The given type for the Terms of Service "terms_type": "default", // Boolean dictating if the user must accept Terms of Service "passive": false, // The id of the root account that owns the Terms of Service "account_id": 1, // Content of the Terms of Service "content": "To be or not to be that is the question", // The type of self registration allowed "self_registration_type": "["none", "observer", "all"]" } ``` #### A HelpLink object looks like: ```js { // The ID of the help link "id": "instructor_question", // The name of the help link "text": "Ask Your Instructor a Question", // The description of the help link "subtext": "Questions are submitted to your instructor", // The URL of the help link "url": "#teacher_feedback", // The type of the help link "type": "default", // The roles that have access to this help link "available_to": ["user", "student", "teacher", "admin", "observer", "unenrolled"] } ``` #### A HelpLinks object looks like: ```js { // Help link button title "help_link_name": "Help And Policies", // Help link button icon "help_link_icon": "help", // Help links defined by the account. Could include default help links. "custom_help_links": [{"id":"link1","text":"Custom Link!","subtext":"Something something.","url":"https:\/\/google.com","type":"custom","available_to":["user","student","teacher","admin","observer","unenrolled"],"is_featured":true,"is_new":false,"feature_headline":"Check this out!"}], // Default help links provided when account has not set help links of their own. "default_help_links": [{"available_to":["student"],"text":"Ask Your Instructor a Question","subtext":"Questions are submitted to your instructor","url":"#teacher_feedback","type":"default","id":"instructor_question","is_featured":false,"is_new":true,"feature_headline":""}, {"available_to":["user","student","teacher","admin","observer","unenrolled"],"text":"Search the Canvas Guides","subtext":"Find answers to common questions","url":"https:\/\/community.canvaslms.com\/t5\/Guides\/ct-p\/guides","type":"default","id":"search_the_canvas_guides","is_featured":false,"is_new":false,"feature_headline":""}, {"available_to":["user","student","teacher","admin","observer","unenrolled"],"text":"Report a Problem","subtext":"If Canvas misbehaves, tell us about it","url":"#create_ticket","type":"default","id":"report_a_problem","is_featured":false,"is_new":false,"feature_headline":""}] } ``` ## [List accounts](#method.accounts.index) [AccountsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts` **Scope:** `url:GET|/api/v1/accounts` A paginated list of accounts that the current user can view or manage. Typically, students and even teachers will get an empty list in response, only account admins can view the accounts that they are in. #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Array of additional information to include."lti\_guid":: the 'tool\_consumer\_instance\_guid' that will be sent for this account on LTI launches"registration\_settings":: returns info about the privacy policy and terms of use"services":: returns services and whether they are enabled (requires account management permissions)"course\_count":: returns the number of courses directly under each account"sub\_account\_count":: returns the number of sub-accounts directly under each account Allowed values: lti\_guid, registration\_settings, services, course\_count, sub\_account\_count | Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [List horizon accounts](#method.accounts.horizon_accounts) [AccountsController#horizon\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/horizon_accounts` **Scope:** `url:GET|/api/v1/horizon_accounts` A paginated list of horizon accounts that the current user can view or manage. Returns all accounts with the horizon\_account setting enabled. If there are any horizon accounts and the user has access to Site Admin, Site Admin will also be included in the results. Typically, students and even teachers will get an empty list in response, only account admins can view the accounts that they are in. #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Array of additional information to include."lti\_guid":: the 'tool\_consumer\_instance\_guid' that will be sent for this account on LTI launches"registration\_settings":: returns info about the privacy policy and terms of use"services":: returns services and whether they are enabled (requires account management permissions)"course\_count":: returns the number of courses directly under each account"sub\_account\_count":: returns the number of sub-accounts directly under each account"site\_admin":: returns true if the account is the Site Admin account (only included if true) Allowed values: lti\_guid, registration\_settings, services, course\_count, sub\_account\_count, site\_admin | Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [Get accounts that admins can manage](#method.accounts.manageable_accounts) [AccountsController#manageable\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/manageable_accounts` **Scope:** `url:GET|/api/v1/manageable_accounts` A paginated list of accounts where the current user has permission to create or manage courses. List will be empty for students and teachers as only admins can view which accounts they are in. Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [Get accounts that users can create courses in](#method.accounts.course_creation_accounts) [AccountsController#course\_creation\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/course_creation_accounts` **Scope:** `url:GET|/api/v1/course_creation_accounts` A paginated list of accounts where the current user has permission to create courses. Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [List accounts for course admins](#method.accounts.course_accounts) [AccountsController#course\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/course_accounts` **Scope:** `url:GET|/api/v1/course_accounts` A paginated list of accounts that the current user can view through their admin course enrollments. (Teacher, TA, or designer enrollments). Only returns "id", "name", "workflow\_state", "root\_account\_id" and "parent\_account\_id" Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [Get a single account](#method.accounts.show) [AccountsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:id` **Scope:** `url:GET|/api/v1/accounts/:id` Retrieve information on an individual account, given by id or sis sis\_account\_id. Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. ## [Settings](#method.accounts.show_settings) [AccountsController#show\_settings](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/settings` **Scope:** `url:GET|/api/v1/accounts/:account_id/settings` Returns a JSON object containing a subset of settings for the specified account. It's possible an empty set will be returned if no settings are applicable. The caller must be an Account admin with the manage\_account\_settings permission. #### Example Request: ```bash curl https:///api/v1/accounts//settings \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js {"microsoft_sync_enabled": true, "microsoft_sync_login_attribute_suffix": false} ``` ## [List environment settings](#method.accounts.environment) [AccountsController#environment](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/settings/environment` **Scope:** `url:GET|/api/v1/settings/environment` Return a hash of global settings for the root account This is the same information supplied to the web interface as +ENV.SETTINGS+. #### Example Request: ```bash curl 'http:///api/v1/settings/environment' \ -H "Authorization: Bearer " ``` #### Example Response: ```js { "calendar_contexts_limit": 10, "open_registration": false, ...} ``` ## [Permissions](#method.accounts.permissions) [AccountsController#permissions](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/permissions` **Scope:** `url:GET|/api/v1/accounts/:account_id/permissions` Returns permission information for the calling user and the given account. You may use `self` as the account id to check permissions against the domain root account. The caller must have an account role or admin (teacher/TA/designer) enrollment in a course in the account. See also the [Course](https://developerdocs.instructure.com/services/canvas/resources/pages/Dq3HF46TIgKustPuq4C9#method.courses.permissions) and [Group](https://developerdocs.instructure.com/services/canvas/resources/pages/2YyNPW0XHYoLadMGQAZY#method.groups.permissions) counterparts. #### Request Parameters: | Parameter | Type | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `permissions[]` | `string` | List of permissions to check against the authenticated user.Permission names are documented in the List assignable permissions endpoint. | #### Example Request: ```bash curl https:///api/v1/accounts/self/permissions \ -H 'Authorization: Bearer ' \ -d 'permissions[]=manage_account_memberships' \ -d 'permissions[]=become_user' ``` #### Example Response: ```js {'manage_account_memberships': 'false', 'become_user': 'true'} ``` ## [Get the sub-accounts of an account](#method.accounts.sub_accounts) [AccountsController#sub\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/sub_accounts` **Scope:** `url:GET|/api/v1/accounts/:account_id/sub_accounts` List accounts that are sub-accounts of the given account. #### Request Parameters: | Parameter | Type | Description | | ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `recursive` | `boolean` | If true, the entire account tree underneaththis account will be returned (though still paginated). If false, onlydirect sub-accounts of this account will be returned. Defaults to false. | | `order` | `string` | Sorts the accounts by id or name.Only applies when recursive is false. Defaults to id. Allowed values: id, name | | `include[]` | `string` | Array of additional information to include."course\_count":: returns the number of courses directly under each account"sub\_account\_count":: returns the number of sub-accounts directly under each account Allowed values: course\_count, sub\_account\_count | #### Example Request: ```bash curl https:///api/v1/accounts//sub_accounts \ -H 'Authorization: Bearer ' ``` Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [Get the Terms of Service](#method.accounts.terms_of_service) [AccountsController#terms\_of\_service](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/terms_of_service` **Scope:** `url:GET|/api/v1/accounts/:account_id/terms_of_service` Returns the terms of service for that account Returns a [TermsOfService](#termsofservice) object. ## [Get help links](#method.accounts.help_links) [AccountsController#help\_links](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/help_links` **Scope:** `url:GET|/api/v1/accounts/:account_id/help_links` Returns the help links for that account Returns a [HelpLinks](#helplinks) object. ## [Get the manually-created courses sub-account for the domain root account](#method.accounts.manually_created_courses_account) [AccountsController#manually\_created\_courses\_account](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/manually_created_courses_account` **Scope:** `url:GET|/api/v1/manually_created_courses_account` Returns the sub-account that contains manually created courses for the domain root account. Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. ## [List active courses in an account](#method.accounts.courses_api) [AccountsController#courses\_api](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/courses` **Scope:** `url:GET|/api/v1/accounts/:account_id/courses` Retrieve a paginated list of courses in this account. #### Request Parameters: | Parameter | Type | Description | | ----------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `with_enrollments` | `boolean` | If true, include only courses with at least one enrollment. If false,include only courses with no enrollments. If not present, do not filteron course enrollment status. | | `enrollment_type[]` | `string` | If set, only return courses that have at least one user enrolled inin the course with one of the specified enrollment types. Allowed values: teacher, student, ta, observer, designer | | `enrollment_workflow_state[]` | `string` | If set, only return courses that have at least one user enrolled inin the course with one of the specified enrollment workflow states. Allowed values: active, completed, deleted, invited, pending, creation\_pending, rejected, inactive | | `published` | `boolean` | If true, include only published courses. If false, exclude publishedcourses. If not present, do not filter on published status. | | `completed` | `boolean` | If true, include only completed courses (these may be in state'completed', or their enrollment term may have ended). If false, excludecompleted courses. If not present, do not filter on completed status. | | `blueprint` | `boolean` | If true, include only blueprint courses. If false, exclude them.If not present, do not filter on this basis. | | `blueprint_associated` | `boolean` | If true, include only courses that inherit content from a blueprint course.If false, exclude them. If not present, do not filter on this basis. | | `public` | `boolean` | If true, include only public courses. If false, exclude them.If not present, do not filter on this basis. | | `by_teachers[]` | `integer` | List of User IDs of teachers; if supplied, include only courses taught byone of the referenced users. | | `by_subaccounts[]` | `integer` | List of Account IDs; if supplied, include only courses associated with oneof the referenced subaccounts. | | `hide_enrollmentless_courses` | `boolean` | If present, only return courses that have at least one enrollment.Equivalent to 'with\_enrollments=true'; retained for compatibility. | | `state[]` | `string` | If set, only return courses that are in the given state(s). By default,all states but "deleted" are returned. Allowed values: created, claimed, available, completed, deleted, all | | `enrollment_term_id[]` | `integer` | If set, only includes courses from the specified terms. Can be either a single ID oran array of enrollment term IDs. | | `search_term` | `string` | The partial course name, code, or full ID to match and return in the results list. Must be at least 3 characters. | | `include[]` | `string` | - All explanations can be seen in the Course API index documentation- "sections", "needs\_grading\_count" and "total\_scores" are not valid options at the account level Allowed values: syllabus\_body, term, course\_progress, storage\_quota\_used\_mb, total\_students, teachers, account\_name, concluded, post\_manually | | `sort` | `string` | The column to sort results by. Allowed values: `course_status`, `course_name`, `sis_course_id`, `teacher`, `account_name` | | `order` | `string` | The order to sort the given column by. Allowed values: `asc`, `desc` | | `search_by` | `string` | The filter to search by. "course" searches for course names, course codes,and SIS IDs. "teacher" searches for teacher names Allowed values: course, teacher | | `starts_before` | `Date` | If set, only return courses that start before the value (inclusive)or their enrollment term starts before the value (inclusive)or both the course's start\_at and the enrollment term's start\_at are set to null.The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. | | `ends_after` | `Date` | If set, only return courses that end after the value (inclusive)or their enrollment term ends after the value (inclusive)or both the course's end\_at and the enrollment term's end\_at are set to null.The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. | | `homeroom` | `boolean` | If set, only return homeroom courses. | Returns a list of [Course](/services/canvas/resources/courses#course) objects. ## [Update an account](#method.accounts.update) [AccountsController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `PUT /api/v1/accounts/:id` **Scope:** `url:PUT|/api/v1/accounts/:id` Update an existing account. #### Request Parameters: | Parameter | Type | Description | | ------------------------------------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account[name]` | `string` | Updates the account name | | `account[sis_account_id]` | `string` | Updates the account sis\_account\_idMust have manage\_sis permission and must not be a root\_account. | | `account[default_time_zone]` | `string` | The default time zone of the account. Allowed time zones areIANA time zones or friendlierRuby on Rails time zones. | | `account[default_storage_quota_mb]` | `integer` | The default course storage quota to be used, if not otherwise specified. | | `account[default_user_storage_quota_mb]` | `integer` | The default user storage quota to be used, if not otherwise specified. | | `account[default_group_storage_quota_mb]` | `integer` | The default group storage quota to be used, if not otherwise specified. | | `account[course_template_id]` | `integer` | The ID of a course to be used as a template for all newly created courses.Empty means to inherit the setting from parent account, 0 means to notuse a template even if a parent account has one set. The course must bemarked as a template. | | `account[parent_account_id]` | `integer` | The ID of a parent account to move the account to. The new parent accountmust be in the same root account as the original. The hierarchy ofsub-accounts will be preserved in the new parent account. The caller mustbe an administrator in both the original parent account and the new parentaccount. | | `account[settings][restrict_student_past_view][value]` | `boolean` | Restrict students from viewing courses after end date | | `account[settings][restrict_student_past_view][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][restrict_student_future_view][value]` | `boolean` | Restrict students from viewing courses before start date | | `account[settings][microsoft_sync_enabled]` | `boolean` | Determines whether this account has Microsoft Teams Sync enabled or not.Note that if you are altering Microsoft Teams sync settings you must enablethe Microsoft Group enrollment syncing feature flag. In addition, if you are enablingMicrosoft Teams sync, you must also specify a tenant, login attribute, and a remote attribute.Specifying a suffix to use is optional. | | `account[settings][microsoft_sync_tenant]` | `string` | The tenant this account should use when using Microsoft Teams Sync.This should be an Azure Active Directory domain name. | | `account[settings][microsoft_sync_login_attribute]` | `string` | The attribute this account should use to lookup users when using Microsoft Teams Sync.Must be one of "sub", "email", "oid", "preferred\_username", or "integration\_id". | | `account[settings][microsoft_sync_login_attribute_suffix]` | `string` | A suffix that will be appended to the result of the login attribute when associatingCanvas users with Microsoft users. Must be under 255 characters and contain no whitespace.This field is optional. | | `account[settings][microsoft_sync_remote_attribute]` | `string` | The Active Directory attribute to use when associating Canvas users with Microsoft users.Must be one of "mail", "mailNickname", or "userPrincipalName". | | `account[settings][restrict_student_future_view][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][lock_all_announcements][value]` | `boolean` | Disable comments on announcements | | `account[settings][lock_all_announcements][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][usage_rights_required][value]` | `boolean` | Copyright and license information must be provided for files before they are published. | | `account[settings][usage_rights_required][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][restrict_student_future_listing][value]` | `boolean` | Restrict students from viewing future enrollments in course list | | `account[settings][restrict_student_future_listing][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][conditional_release][value]` | `boolean` | Enable or disable individual learning paths for students based on assessment | | `account[settings][conditional_release][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][enable_course_paces][value]` | `boolean` | Enable or disable course pacing | | `account[settings][enable_course_paces][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][suppress_notifications]` | `boolean` | Suppress notification messages from being created and sent. When set to+true+, all notifications are suppressed. When set to an array ofnotification category slugs (e.g. +\["grading", "announcement"]+), onlynotifications in those categories are suppressed. Set to +false+ toallow all notifications. Root account setting only. | | `account[settings][password_policy]` | `Hash` | Hash of optional password policy configuration parameters for a root account+allow\_login\_suspension+ boolean:: Allow suspension of user logins upon reaching maximum\_login\_attempts+require\_number\_characters+ boolean:: Require the use of number characters when setting up a new password+require\_symbol\_characters+ boolean:: Require the use of symbol characters when setting up a new password+minimum\_character\_length+ integer:: Minimum number of characters required for a new password+maximum\_login\_attempts+ integer:: Maximum number of login attempts before a user is locked outRequired feature option:Enhance password options | | `account[settings][enable_as_k5_account][value]` | `boolean` | Enable or disable Canvas for Elementary for this account | | `account[settings][use_classic_font_in_k5][value]` | `boolean` | Whether or not the classic font is used on the dashboard. Only applies if enable\_as\_k5\_account is true. | | `account[settings][horizon_account][value]` | `boolean` | Enable or disable Canvas Career for this account | | `override_sis_stickiness` | `boolean` | Default is true. If false, any fields containing “sticky” changes will not be updated.See SIS CSV Format documentation for information on which fields can have SIS stickiness | | `account[settings][lock_outcome_proficiency][value]` | `boolean` | \[DEPRECATED] Restrict instructors from changing mastery scale | | `account[lock_outcome_proficiency][locked]` | `boolean` | \[DEPRECATED] Lock this setting for sub-accounts and courses | | `account[settings][lock_proficiency_calculation][value]` | `boolean` | \[DEPRECATED] Restrict instructors from changing proficiency calculation method | | `account[lock_proficiency_calculation][locked]` | `boolean` | \[DEPRECATED] Lock this setting for sub-accounts and courses | | `account[services]` | `Hash` | Give this a set of keys and boolean values to enable or disable services matching the keys | #### Example Request: ```bash curl https:///api/v1/accounts/ \ -X PUT \ -H 'Authorization: Bearer ' \ -d 'account[name]=New account name' \ -d 'account[default_time_zone]=Mountain Time (US & Canada)' \ -d 'account[default_storage_quota_mb]=450' ``` Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. ## [Delete a user from the root account](#method.accounts.remove_user) [AccountsController#remove\_user](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `DELETE /api/v1/accounts/:account_id/users/:user_id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/users/:user_id` Delete a user record from a Canvas root account. If a user is associated with multiple root accounts (in a multi-tenant instance of Canvas), this action will NOT remove them from the other accounts. WARNING: This API will allow a user to remove themselves from the account. If they do this, they won't be able to make API calls or log into Canvas at that account. #### Example Request: ```bash curl https:///api/v1/accounts/3/users/5 \ -H 'Authorization: Bearer ' \ -X DELETE ``` Returns an [User](/services/canvas/resources/users#user) object. ## [Delete multiple users from the root account](#method.accounts.remove_users) [AccountsController#remove\_users](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `DELETE /api/v1/accounts/:account_id/users` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/users` Delete multiple users from a Canvas root account. If a user is associated with multiple root accounts (in a multi-tenant instance of Canvas), this action will NOT remove them from the other accounts. WARNING: This API will allow a user to remove themselves from the account. If they do this, they won't be able to make API calls or log into Canvas at that account. #### Example Request: ```bash curl https:///api/v1/accounts/3/users \ -H 'Authorization: Bearer ' \ -X DELETE -d 'user_ids[]=1' \ -d 'user_ids[]=2' ``` Returns a [Progress](/services/canvas/resources/progress#progress) object. ## [Update multiple users](#method.accounts.update_users) [AccountsController#update\_users](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `PUT /api/v1/accounts/:account_id/users/bulk_update` **Scope:** `url:PUT|/api/v1/accounts/:account_id/users/bulk_update` Updates multiple users in bulk. #### Request Parameters: | Parameter | Type | Description | | ---------- | -------- | ------------------------------------------------------------ | | `user_ids` | `string` | \[Array\]The IDs of the users to update. | | `user` | `Hash` | The attributes to update for each user. | #### Example Request: ```bash curl https:///api/v1/accounts/3/users/bulk_update \ -X PUT \ -H 'Authorization: Bearer ' \ -d 'user_ids[]=1' \ -d 'user_ids[]=2' \ -d 'user[event]=suspend' ``` Returns a [Progress](/services/canvas/resources/progress#progress) object. ## [Restore a deleted user from a root account](#method.accounts.restore_user) [AccountsController#restore\_user](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `PUT /api/v1/accounts/:account_id/users/:user_id/restore` **Scope:** `url:PUT|/api/v1/accounts/:account_id/users/:user_id/restore` Restore a user record along with the most recently deleted pseudonym from a Canvas root account. #### Example Request: ```bash curl https:///api/v1/accounts/3/users/5/restore \ -H 'Authorization: Bearer ' \ -X PUT ``` Returns an [User](/services/canvas/resources/users#user) object. ## [Create a new sub-account](#method.sub_accounts.create) [SubAccountsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/sub_accounts_controller.rb) #### `POST /api/v1/accounts/:account_id/sub_accounts` **Scope:** `url:POST|/api/v1/accounts/:account_id/sub_accounts` Add a new sub-account to a given account. #### Request Parameters: | Parameter | Type | Description | | ----------------------------------------- | ----------------- | ------------------------------------------------------------------------ | | `account[name]` | Required `string` | The name of the new sub-account. | | `account[sis_account_id]` | `string` | The account's identifier in the Student Information System. | | `account[default_storage_quota_mb]` | `integer` | The default course storage quota to be used, if not otherwise specified. | | `account[default_user_storage_quota_mb]` | `integer` | The default user storage quota to be used, if not otherwise specified. | | `account[default_group_storage_quota_mb]` | `integer` | The default group storage quota to be used, if not otherwise specified. | Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. ## [Delete a sub-account](#method.sub_accounts.destroy) [SubAccountsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/sub_accounts_controller.rb) #### `DELETE /api/v1/accounts/:account_id/sub_accounts/:id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/sub_accounts/:id` Cannot delete an account with active courses or active sub\_accounts. Cannot delete a root\_account Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Accounts (LTI) API for accessing account data using an LTI dev key. Allows a tool to get account information via LTI Advantage authorization scheme, which does not require a user session like normal developer keys do. Requires the account lookup scope on the LTI key. #### An Account object looks like: ```js { // the ID of the Account object "id": 2, // The display name of the account "name": "Canvas Account", // The UUID of the account "uuid": "WvAHhY5FINzq5IyRIJybGeiXyFkG3SqHUPb7jZY5", // The account's parent ID, or null if this is the root account "parent_account_id": 1, // The ID of the root account, or null if this is the root account "root_account_id": 1, // The state of the account. Can be 'active' or 'deleted'. "workflow_state": "active" } ``` ## [Get account](#method.lti/account_lookup.show) [Lti::AccountLookupController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/account_lookup_controller.rb) #### `GET /api/lti/accounts/:account_id` **Scope:** `url:GET|/api/lti/accounts/:account_id` Retrieve information on an individual account, given by local or global ID. Returns an [Account](#account) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Admins Manage account role assignments #### An Admin object looks like: ```js { // The unique identifier for the account role/user assignment. "id": 1023, // The account role assigned. This can be 'AccountAdmin' or a user-defined role // created by the Roles API. "role": "AccountAdmin", // The user the role is assigned to. See the Users API for details. "user": null, // The status of the account role/user assignment. "workflow_state": "deleted" } ``` ## [List account admins](#method.admins.index) [AdminsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/admins_controller.rb) #### `GET /api/v1/accounts/:account_id/admins` **Scope:** `url:GET|/api/v1/accounts/:account_id/admins` A paginated list of the admins in the account #### Request Parameters: | Parameter | Type | Description | | ----------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- | | `user_id[]` | `[Integer]` | Scope the results to those with user IDs equal to any of the IDs specified here. | | `search_term` | `string` | The partial name or full ID of the admins to match and return in theresults list. Must be at least 2 characters. | | `include_deleted` | `boolean` | When set to true, returns admins who have been deleted | Returns a list of [Admin](#admin) objects. ## [Make an account admin](#method.admins.create) [AdminsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/admins_controller.rb) #### `POST /api/v1/accounts/:account_id/admins` **Scope:** `url:POST|/api/v1/accounts/:account_id/admins` Flag an existing user as an admin within the account. #### Request Parameters: | Parameter | Type | Description | | ------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | Required `integer` | The id of the user to promote. | | `role` | `string` | \[DEPRECATED] The user's admin relationship with the account will becreated with the given role. Defaults to 'AccountAdmin'. | | `role_id` | `integer` | The user's admin relationship with the account will be created with the given role. Defaults to the built-in role for 'AccountAdmin'. | | `send_confirmation` | `boolean` | Send a notification email tothe new admin if true. Default is true. | Returns an [Admin](#admin) object. ## [Remove account admin](#method.admins.destroy) [AdminsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/admins_controller.rb) #### `DELETE /api/v1/accounts/:account_id/admins/:user_id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/admins/:user_id` Remove the rights associated with an account admin role from a user. #### Request Parameters: | Parameter | Type | Description | | --------- | ------------------ | ------------------------------------------------------------------------------- | | `role` | `string` | \[DEPRECATED] Account role to remove from the user. | | `role_id` | Required `integer` | The id of the role representing the user's admin relationship with the account. | Returns an [Admin](#admin) object. ## [List my admin roles](#method.admins.self_roles) [AdminsController#self\_roles](https://github.com/instructure/canvas-lms/blob/master/app/controllers/admins_controller.rb) #### `GET /api/v1/accounts/:account_id/admins/self` **Scope:** `url:GET|/api/v1/accounts/:account_id/admins/self` A paginated list of the current user's roles in the account. The results are the same as those returned by the [List account admins](#method.admins.index) endpoint with +user\_id+ set to +self+, except the "Admins - Add / Remove" permission is not required. Returns a list of [Admin](#admin) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # AI Conversations API for managing conversations with AI Experiences. ## [Show conversation](#method.ai_conversations.show) [AiConversationsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id` Get a specific conversation by ID (for teachers viewing student conversations) ## [Get active conversation](#method.ai_conversations.active_conversation) [AiConversationsController#active\_conversation](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations` Get the active conversation for the current user and AI experience ## [Create AI conversation](#method.ai_conversations.create) [AiConversationsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations` Initialize a new conversation with the AI experience ## [Post message to conversation](#method.ai_conversations.post_message) [AiConversationsController#post\_message](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages` Send a message to an existing conversation and get the AI response #### Request Parameters: | Parameter | Type | Description | | --------- | ----------------- | ------------------------------------ | | `message` | Required `string` | The user's message to send to the AI | ## [Delete AI conversation](#method.ai_conversations.destroy) [AiConversationsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `DELETE /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id` End the current conversation session ## [Get conversation evaluation](#method.ai_conversations.evaluation) [AiConversationsController#evaluation](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/evaluation` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/evaluation` Fetch the latest stored evaluation for a conversation from the llm-conversation service. Reads only — does not run the LLM and is not rate-limited. `evaluation` is null when none has been generated yet (llma returns 200 + null, never 404, so this is distinguishable from an outage). `stale` is true when the AI experience was edited after the stored evaluation was generated. ## [Generate conversation evaluation](#method.ai_conversations.create_evaluation) [AiConversationsController#create\_evaluation](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/evaluation` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/evaluation` Run the LLM to (re)generate an evaluation for a conversation and persist it in the llm-conversation service. Rate-limited. Also the Reset path — a fresh run replaces any prior stored evaluation. ## [Create feedback on a conversation message](#method.ai_conversations.create_feedback) [AiConversationsController#create\_feedback](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages/:message_id/feedback` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages/:message_id/feedback` Submit a like or dislike vote on an AI-generated message. Ownership: load\_conversation gates this action — only the conversation owner or a course manager reaches here. Sub-resource (message\_id within the conversation) scoping is delegated to llma. #### Request Parameters: | Parameter | Type | Description | | ------------------ | ----------------- | ----------------------------- | | `vote` | Required `string` | "liked" or "disliked" | | `message_id` | Required `string` | llm-conversation message UUID | | `feedback_message` | `string` | optional text for dislike | ## [Delete feedback on a conversation message](#method.ai_conversations.delete_feedback) [AiConversationsController#delete\_feedback](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `DELETE /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages/:message_id/feedback/:feedback_id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages/:message_id/feedback/:feedback_id` Remove a previously submitted vote (toggling off like/dislike). Ownership: load\_conversation gates this action — only the conversation owner or a course manager reaches here. Sub-resource (message\_id, feedback\_id within the conversation) scoping is delegated to llma. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # AI Experiences API for creating, accessing and updating AI Experiences. AI Experiences are used to create interactive AI-powered learning scenarios within courses. #### An AiExperience object looks like: ```js // An AI Experience for interactive learning { // The ID of the AI experience "id": 234, // The title for the AI experience "title": "Customer Service Simulation", // The description of the AI experience "description": "Practice customer service skills in a simulated environment", // The AI facts for the experience (optional) "facts": "You are a customer service representative...", // The learning objectives for this experience "learning_objective": "Students will practice active listening and problem-solving", // The pedagogical guidance for the experience "pedagogical_guidance": "A customer is calling about a billing issue", // The current published state of the AI experience "workflow_state": "published", // The course this experience belongs to "course_id": 1578941 } ``` ## [List AI experiences](#method.ai_experiences.index) [AiExperiencesController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences` Retrieve the paginated list of AI experiences for a course #### Request Parameters: | Parameter | Type | Description | | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `workflow_state` | `string` | Only return experiences with the specified workflow state.Allowed values: published, unpublished, deleted | Returns a list of [AiExperience](#aiexperience) objects. ## [Show an AI experience](#method.ai_experiences.show) [AiExperiencesController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:id` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id` Retrieve an AI experience by ID Returns an [AiExperience](#aiexperience) object. ## [Show new AI experience form](#method.ai_experiences.new) [AiExperiencesController#new](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/new` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/new` Display the form for creating a new AI experience ## [Show edit AI experience form](#method.ai_experiences.edit) [AiExperiencesController#edit](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:id/edit` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id/edit` Display the form for editing an existing AI experience ## [Create an AI experience](#method.ai_experiences.create) [AiExperiencesController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences` Create a new AI experience for the specified course #### Request Parameters: | Parameter | Type | Description | | ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | `title` | Required `string` | The title of the AI experience. | | `description` | `string` | The description of the AI experience. | | `facts` | `string` | The AI facts for the experience. | | `learning_objective` | Required `string` | The learning objectives for this experience. | | `pedagogical_guidance` | Required `string` | The pedagogical guidance for the experience. | | `workflow_state` | `string` | The initial state of the experience. Defaults to 'unpublished'.Allowed values: published, unpublished | Returns an [AiExperience](#aiexperience) object. ## [Update an AI experience](#method.ai_experiences.update) [AiExperiencesController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `PUT /api/v1/courses/:course_id/ai_experiences/:id` **Scope:** `url:PUT|/api/v1/courses/:course_id/ai_experiences/:id` Update an existing AI experience #### Request Parameters: | Parameter | Type | Description | | ---------------------- | ----------------- | ----------------------------------------------------------------------------- | | `title` | `string` | The title of the AI experience. | | `description` | `string` | The description of the AI experience. | | `facts` | `string` | The AI facts for the experience. | | `learning_objective` | Required `string` | The learning objectives for this experience. | | `pedagogical_guidance` | Required `string` | The pedagogical guidance for the experience. | | `workflow_state` | `string` | The state of the experience.Allowed values: published, unpublished | Returns an [AiExperience](#aiexperience) object. ## [Delete an AI experience](#method.ai_experiences.destroy) [AiExperiencesController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `DELETE /api/v1/courses/:course_id/ai_experiences/:id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/ai_experiences/:id` Delete an AI experience (soft delete - marks as deleted) Returns an [AiExperience](#aiexperience) object. ## [List student AI conversations](#method.ai_experiences.ai_conversations_index) [AiExperiencesController#ai\_conversations\_index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:id/ai_conversations` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id/ai_conversations` Retrieve the latest AI conversation for each student in the course for this AI experience. Only available to teachers and course managers. ## [Show student AI conversation](#method.ai_experiences.ai_conversation_show) [AiExperiencesController#ai\_conversation\_show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:id/ai_conversations/:conversation_id` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id/ai_conversations/:conversation_id` Retrieve a specific student's AI conversation with full message history. Only available to teachers and course managers. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Analytics API for retrieving the data exposed in Canvas Analytics ## [Get department-level participation data](#method.analytics_api.department_participation) #### `GET /api/v1/accounts/:account_id/analytics/terms/:term_id/activity` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/activity` #### `GET /api/v1/accounts/:account_id/analytics/current/activity` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/current/activity` #### `GET /api/v1/accounts/:account_id/analytics/completed/activity` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/completed/activity` Returns page view hits summed across all courses in the department. Two groupings of these counts are returned; one by day (+by\_date+), the other by category (+by\_category+). The possible categories are announcements, assignments, collaborations, conferences, discussions, files, general, grades, groups, modules, other, pages, and quizzes. This and the other department-level endpoints have three variations which all return the same style of data but for different subsets of courses. All share the prefix /api/v1/accounts/\/analytics. The possible suffixes are: * /current: includes all available courses in the default term * /completed: includes all concluded courses in the default term * /terms/\: includes all available or concluded courses in the given term. Courses not yet offered or which have been deleted are never included. /current and /completed are intended for use when the account has only one term. /terms/\ is intended for use when the account has multiple terms. The action follows the suffix. #### Example Request: ```bash curl https:///api/v1/accounts//analytics/current/activity \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/completed/activity \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/terms//activity \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "by_date": { "2012-01-24": 1240, "2012-01-27": 912, }, "by_category": { "announcements": 54, "assignments": 256, "collaborations": 18, "conferences": 26, "discussions": 354, "files": 132, "general": 59, "grades": 177, "groups": 132, "modules": 71, "other": 412, "pages": 105, "quizzes": 356 }, } ``` ## [Get department-level grade data](#method.analytics_api.department_grades) #### `GET /api/v1/accounts/:account_id/analytics/terms/:term_id/grades` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/grades` #### `GET /api/v1/accounts/:account_id/analytics/current/grades` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/current/grades` #### `GET /api/v1/accounts/:account_id/analytics/completed/grades` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/completed/grades` Returns the distribution of grades for students in courses in the department. Each data point is one student's current grade in one course; if a student is in multiple courses, he contributes one value per course, but if he's enrolled multiple times in the same course (e.g. a lecture section and a lab section), he only constributes on value for that course. Grades are binned to the nearest integer score; anomalous grades outside the 0 to 100 range are ignored. The raw counts are returned, not yet normalized by the total count. Shares the same variations on endpoint as the participation data. #### Example Request: ```bash curl https:///api/v1/accounts//analytics/current/grades \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/completed/grades \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/terms//grades \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "0": 95, "1": 1, "2": 0, "3": 0, ... "93": 125, "94": 110, "95": 142, "96": 157, "97": 116, "98": 85, "99": 63, "100": 190 } ``` ## [Get department-level statistics](#method.analytics_api.department_statistics) #### `GET /api/v1/accounts/:account_id/analytics/terms/:term_id/statistics` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/statistics` #### `GET /api/v1/accounts/:account_id/analytics/current/statistics` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/current/statistics` #### `GET /api/v1/accounts/:account_id/analytics/completed/statistics` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/completed/statistics` Returns numeric statistics about the department and term (or filter). Shares the same variations on endpoint as the participation data. #### Example Request: ```bash curl https:///api/v1/accounts//analytics/current/statistics \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/completed/statistics \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/terms//statistics \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "courses": 27, "subaccounts": 3, "teachers": 36, "students": 418, "discussion_topics": 77, "media_objects": 219, "attachments": 1268, "assignments": 290, } ``` ## [Get department-level statistics, broken down by subaccount](#method.analytics_api.department_statistics_by_subaccount) #### `GET /api/v1/accounts/:account_id/analytics/terms/:term_id/statistics_by_subaccount` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/statistics_by_subaccount` #### `GET /api/v1/accounts/:account_id/analytics/current/statistics_by_subaccount` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/current/statistics_by_subaccount` #### `GET /api/v1/accounts/:account_id/analytics/completed/statistics_by_subaccount` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/completed/statistics_by_subaccount` Returns numeric statistics about the department subaccounts and term (or filter). Shares the same variations on endpoint as the participation data. #### Example Request: ```bash curl https:///api/v1/accounts//analytics/current/statistics_by_subaccount \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/completed/statistics_by_subaccount \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/terms//statistics_by_subaccount \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js {"accounts": [ { "name": "some string", "id": 188, "courses": 27, "teachers": 36, "students": 418, "discussion_topics": 77, "media_objects": 219, "attachments": 1268, "assignments": 290, } ]} ``` ## [Get course-level participation data](#method.analytics_api.course_participation) #### `GET /api/v1/courses/:course_id/analytics/activity` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/activity` Returns page view hits and participation numbers grouped by day through the entire history of the course. Page views is returned as a hash, where the hash keys are dates in the format "YYYY-MM-DD". The page\_views result set includes page views broken out by access category. Participations is returned as an array of dates in the format "YYYY-MM-DD". #### Example Request: ```bash curl https:///api/v1/courses//analytics/activity \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [ { "date": "2012-01-24", "participations": 3, "views": 10 } ] ``` ## [Get course-level assignment data](#method.analytics_api.course_assignments) #### `GET /api/v1/courses/:course_id/analytics/assignments` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/assignments` Returns a list of assignments for the course sorted by due date. For each assignment returns basic assignment information, the grade breakdown, and a breakdown of on-time/late status of homework submissions. #### Request Parameters: | Parameter | Type | Description | | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `async` | `boolean` | If async is true, then the course\_assignments call can happen asynch-ronously and MAY return a response containing a progress\_url key insteadof an assignments array. If it does, then it is the caller'sresponsibility to poll the API again to see if the progress is complete.If the data is ready (possibly even on the first async call) then itwill be passed back normally, as documented in the example response. | #### Example Request: ```bash curl https:///api/v1/courses//analytics/assignments \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [ { "assignment_id": 1234, "title": "Assignment 1", "points_possible": 10, "due_at": "2012-01-25T22:00:00-07:00", "unlock_at": "2012-01-20T22:00:00-07:00", "muted": false, "min_score": 2, "max_score": 10, "median": 7, "first_quartile": 4, "third_quartile": 8, "tardiness_breakdown": { "on_time": 0.75, "missing": 0.1, "late": 0.15 } }, { "assignment_id": 1235, "title": "Assignment 2", "points_possible": 15, "due_at": "2012-01-26T22:00:00-07:00", "unlock_at": null, "muted": true, "min_score": 8, "max_score": 8, "median": 8, "first_quartile": 8, "third_quartile": 8, "tardiness_breakdown": { "on_time": 0.65, "missing": 0.12, "late": 0.23 "total": 275 } } ] ``` ## [Get course-level student summary data](#method.analytics_api.course_student_summaries) #### `GET /api/v1/courses/:course_id/analytics/student_summaries` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/student_summaries` Returns a summary of per-user access information for all students in a course. This includes total page views, total participations, and a breakdown of on-time/late status for all homework submissions in the course. Each student's summary also includes the maximum number of page views and participations by any student in the course, which may be useful for some visualizations (since determining maximums client side can be tricky with pagination). #### Request Parameters: | Parameter | Type | Description | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sort_column` | `string` | The order results in which results are returned. Defaults to "name". Allowed values: `name`, `name_descending`, `score`, `score_descending`, `participations`, `participations_descending`, `page_views`, `page_views_descending` | | `student_id` | `string` | If set, returns only the specified student. | #### Example Request: ```bash curl https:///api/v1/courses//analytics/student_summaries \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [ { "id": 2346, "page_views": 351, "page_views_level": "1" "max_page_view": 415, "participations": 1, "participations_level": "3", "max_participations": 10, "tardiness_breakdown": { "total": 5, "on_time": 3, "late": 0, "missing": 2, "floating": 0 } }, { "id": 2345, "page_views": 124, "participations": 15, "tardiness_breakdown": { "total": 5, "on_time": 1, "late": 2, "missing": 3, "floating": 0 } } ] ``` ## [Get user-in-a-course-level participation data](#method.analytics_api.student_in_course_participation) #### `GET /api/v1/courses/:course_id/analytics/users/:student_id/activity` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/activity` Returns page view hits grouped by hour, and participation details through the entire history of the course. `page_views` are returned as a hash, where the keys are iso8601 dates, bucketed by the hour. `participations` are returned as an array of hashes, sorted oldest to newest. #### Example Request: ```bash curl https:///api/v1/courses//analytics/users//activity \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "page_views": { "2012-01-24T13:00:00-00:00": 19, "2012-01-24T14:00:00-00:00": 13, "2012-01-27T09:00:00-00:00": 23 }, "participations": [ { "created_at": "2012-01-21T22:00:00-06:00", "url": "https://canvas.example.com/path/to/canvas", }, { "created_at": "2012-01-27T22:00:00-06:00", "url": "https://canvas.example.com/path/to/canvas", } ] } ``` ## [Get user-in-a-course-level assignment data](#method.analytics_api.student_in_course_assignments) #### `GET /api/v1/courses/:course_id/analytics/users/:student_id/assignments` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/assignments` Returns a list of assignments for the course sorted by due date. For each assignment returns basic assignment information, the grade breakdown (including the student's actual grade), and the basic submission information for the student's submission if it exists. #### Example Request: ```bash curl https:///api/v1/courses//analytics/users//assignments \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [ { "assignment_id": 1234, "title": "Assignment 1", "points_possible": 10, "due_at": "2012-01-25T22:00:00-07:00", "unlock_at": "2012-01-20T22:00:00-07:00", "muted": false, "min_score": 2, "max_score": 10, "median": 7, "first_quartile": 4, "third_quartile": 8, "module_ids": [ 1, 2 ], "submission": { "posted_at": "2012-01-23T20:00:00-07:00", "submitted_at": "2012-01-22T22:00:00-07:00", "score": 10 } }, { "assignment_id": 1235, "title": "Assignment 2", "points_possible": 15, "due_at": "2012-01-26T22:00:00-07:00", "unlock_at": null, "muted": true, "min_score": 8, "max_score": 8, "median": 8, "first_quartile": 8, "third_quartile": 8, "module_ids": [ 1 ], "submission": { "posted_at": null, "submitted_at": "2012-01-22T22:00:00-07:00" } } ] ``` ## [Get user-in-a-course-level messaging data](#method.analytics_api.student_in_course_messaging) #### `GET /api/v1/courses/:course_id/analytics/users/:student_id/communication` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/communication` Returns messaging "hits" grouped by day through the entire history of the course. Returns a hash containing the number of instructor-to-student messages, and student-to-instructor messages, where the hash keys are dates in the format "YYYY-MM-DD". Message hits include Conversation messages and comments on homework submissions. #### Example Request: ```bash curl https:///api/v1/courses//analytics/users//communication \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "2012-01-24":{ "instructorMessages":1, "studentMessages":2 }, "2012-01-27":{ "studentMessages":1 } } ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Announcement External Feeds External feeds represent RSS feeds that can be attached to a Course or Group, in order to automatically create announcements for each new item in the feed. #### An ExternalFeed object looks like: ```js { // The ID of the feed "id": 5, // The title of the feed, pulled from the feed itself. If the feed hasn't yet // been pulled, a temporary name will be synthesized based on the URL "display_name": "My Blog", // The HTTP/HTTPS URL to the feed "url": "http://example.com/myblog.rss", // If not null, only feed entries whose title contains this string will trigger // new posts in Canvas "header_match": "pattern", // When this external feed was added to Canvas "created_at": "2012-06-01T00:00:00-06:00", // The verbosity setting determines how much of the feed's content is imported // into Canvas as part of the posting. 'link_only' means that only the title and // a link to the item. 'truncate' means that a summary of the first portion of // the item body will be used. 'full' means that the full item body will be // used. "verbosity": "truncate" } ``` ## [List external feeds](#method.external_feeds.index) [ExternalFeedsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/external_feeds_controller.rb) #### `GET /api/v1/courses/:course_id/external_feeds` **Scope:** `url:GET|/api/v1/courses/:course_id/external_feeds` #### `GET /api/v1/groups/:group_id/external_feeds` **Scope:** `url:GET|/api/v1/groups/:group_id/external_feeds` Returns the paginated list of External Feeds this course or group. #### Example Request: ```bash curl https:///api/v1/courses//external_feeds \ -H 'Authorization: Bearer ' ``` Returns a list of [ExternalFeed](#externalfeed) objects. ## [Create an external feed](#method.external_feeds.create) [ExternalFeedsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/external_feeds_controller.rb) #### `POST /api/v1/courses/:course_id/external_feeds` **Scope:** `url:POST|/api/v1/courses/:course_id/external_feeds` #### `POST /api/v1/groups/:group_id/external_feeds` **Scope:** `url:POST|/api/v1/groups/:group_id/external_feeds` Create a new external feed for the course or group. #### Request Parameters: | Parameter | Type | Description | | -------------- | ----------------- | ------------------------------------------------------------------------------------ | | `url` | Required `string` | The url to the external rss or atom feed | | `header_match` | `boolean` | If given, only feed entries that contain this string in their title will be imported | | `verbosity` | `string` | Defaults to "full" Allowed values: `full`, `truncate`, `link_only` | #### Example Request: ```bash curl https:///api/v1/courses//external_feeds \ -F url='http://example.com/rss.xml' \ -F header_match='news flash!' \ -F verbosity='full' \ -H 'Authorization: Bearer ' ``` Returns an [ExternalFeed](#externalfeed) object. ## [Delete an external feed](#method.external_feeds.destroy) [ExternalFeedsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/external_feeds_controller.rb) #### `DELETE /api/v1/courses/:course_id/external_feeds/:external_feed_id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/external_feeds/:external_feed_id` #### `DELETE /api/v1/groups/:group_id/external_feeds/:external_feed_id` **Scope:** `url:DELETE|/api/v1/groups/:group_id/external_feeds/:external_feed_id` Deletes the external feed. #### Example Request: ```bash curl -X DELETE https:///api/v1/courses//external_feeds/ \ -H 'Authorization: Bearer ' ``` Returns an [ExternalFeed](#externalfeed) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Announcements API for retrieving announcements. This API is Announcement-specific. See also the Discussion Topics API, which operates on Announcements also. ## [List announcements](#method.announcements_api.index) [AnnouncementsApiController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/announcements_api_controller.rb) #### `GET /api/v1/announcements` **Scope:** `url:GET|/api/v1/announcements` Returns the paginated list of announcements for the given courses and date range. Note that a +context\_code+ field is added to the responses so you can tell which course each announcement belongs to. #### Request Parameters: | Parameter | Type | Description | | ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `context_codes[]` | Required `string` | List of context\_codes to retrieve announcements for (for example, +course\_123+). Only coursesare presently supported. The call will fail unless the caller has View Announcements permissionin all listed courses. | | `start_date` | `Date` | Only return announcements posted since the start\_date (inclusive).Defaults to 14 days ago. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. | | `end_date` | `Date` | Only return announcements posted before the end\_date (inclusive).Defaults to 28 days from start\_date. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.Announcements scheduled for future posting will only be returned to course administrators. | | `available_after` | `Date` | Only return announcements having locked\_at nil or after available\_after (exclusive).The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.Effective only for students (who don't have moderate forum right). | | `active_only` | `boolean` | Only return active announcements that have been published.Applies only to requesting users that have permission to viewunpublished items.Defaults to false for users with access to view unpublished items,otherwise true and unmodifiable. | | `latest_only` | `boolean` | Only return the latest announcement for each associated context.The response will include at most one announcement for eachspecified context in the context\_codes\[] parameter.Defaults to false. | | `include` | `array` | Optional list of resources to include with the response. May includea string of the name of the resource. Possible values are:"sections", "sections\_user\_count"if "sections" is passed, includes the course sections that are associatedwith the topic, if the topic is specific to certain sections of the course.If "sections\_user\_count" is passed, then:(a) If sections were asked for and the topic is specific to certaincourse sections sections, includes the number of users in eachsection. (as part of the section json asked for above)(b) Else, includes at the root level the total number of users in thetopic's context (group or course) that the topic applies to. | #### Example Request: ```bash curl https:///api/v1/announcements?context_codes[]=course_1&context_codes[]=course_2 \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [{ "id": 1, "title": "Hear ye", "message": "Henceforth, all assignments must be...", "posted_at": "2017-01-31T22:00:00Z", "delayed_post_at": null, "context_code": "course_2", ... }] ``` Returns a list of [DiscussionTopic](/services/canvas/resources/discussion_topics#discussiontopic) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # API Token Scopes {% hint style="warning" %} BETA: This API resource is not finalized, and there could be breaking changes before its final release. {% endhint %} API for retrieving API scopes #### A Scope object looks like: ```js { // The resource the scope is associated with "resource": "courses", // The localized resource name "resource_name": "Courses", // The controller the scope is associated to "controller": "courses", // The controller action the scope is associated to "action": "index", // The HTTP verb for the scope "verb": "GET", // The identifier for the scope "scope": "url:GET|/api/v1/courses" } ``` ## [List scopes](#method.scopes_api.index) [ScopesApiController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/scopes_api_controller.rb) {% hint style="warning" %} BETA: This API endpoint is not finalized, and there could be breaking changes before its final release. {% endhint %} #### `GET /api/v1/accounts/:account_id/scopes` **Scope:** `url:GET|/api/v1/accounts/:account_id/scopes` A list of scopes that can be applied to developer keys and access tokens. #### Request Parameters: | Parameter | Type | Description | | ---------- | -------- | ----------------------------------------------------------------------------------------------------- | | `group_by` | `string` | The attribute to group the scopes by. By default no grouping is done. Allowed values: `resource_name` | Returns a list of [Scope](#scope) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Appointment Groups API for creating, accessing and updating appointment groups. Appointment groups provide a way of creating a bundle of time slots that users can sign up for (e.g. "Office Hours" or "Meet with professor about Final Project"). Both time slots and reservations of time slots are stored as Calendar Events. #### An Appointment object looks like: ```js // Date and time for an appointment { // The appointment identifier. "id": 987, // Start time for the appointment "start_at": "2012-07-20T15:00:00-06:00", // End time for the appointment "end_at": "2012-07-20T15:00:00-06:00" } ``` #### An AppointmentGroup object looks like: ```js { // The ID of the appointment group "id": 543, // The title of the appointment group "title": "Final Presentation", // The start of the first time slot in the appointment group "start_at": "2012-07-20T15:00:00-06:00", // The end of the last time slot in the appointment group "end_at": "2012-07-20T17:00:00-06:00", // The text description of the appointment group "description": "Es muy importante", // The location name of the appointment group "location_name": "El Tigre Chino's office", // The address of the appointment group's location "location_address": "Room 234", // The number of participant who have reserved slots (see include[] argument) "participant_count": 2, // The start and end times of slots reserved by the current user as well as the // id of the calendar event for the reservation (see include[] argument) "reserved_times": [{"id":987,"start_at":"2012-07-20T15:00:00-06:00","end_at":"2012-07-20T15:00:00-06:00"}], // Boolean indicating whether observer users should be able to sign-up for an // appointment "allow_observer_signup": false, // The context codes (i.e. courses) this appointment group belongs to. Only // people in these courses will be eligible to sign up. "context_codes": ["course_123"], // The sub-context codes (i.e. course sections and group categories) this // appointment group is restricted to "sub_context_codes": [course_section_234], // Current state of the appointment group ('pending', 'active' or 'deleted'). // 'pending' indicates that it has not been published yet and is invisible to // participants. "workflow_state": "active", // Boolean indicating whether the current user needs to sign up for this // appointment group (i.e. it's reservable and the // min_appointments_per_participant limit has not been met by this user). "requiring_action": true, // Number of time slots in this appointment group "appointments_count": 2, // Calendar Events representing the time slots (see include[] argument) Refer to // the Calendar Events API for more information "appointments": [], // Newly created time slots (same format as appointments above). Only returned // in Create/Update responses where new time slots have been added "new_appointments": [], // Maximum number of time slots a user may register for, or null if no limit "max_appointments_per_participant": 1, // Minimum number of time slots a user must register for. If not set, users do // not need to sign up for any time slots "min_appointments_per_participant": 1, // Maximum number of participants that may register for each time slot, or null // if no limit "participants_per_appointment": 1, // 'private' means participants cannot see who has signed up for a particular // time slot, 'protected' means that they can "participant_visibility": "private", // Indicates how participants sign up for the appointment group, either as // individuals ('User') or in student groups ('Group'). Related to // sub_context_codes (i.e. 'Group' signups always have a single group category) "participant_type": "User", // URL for this appointment group (to update, delete, etc.) "url": "https://example.com/api/v1/appointment_groups/543", // URL for a user to view this appointment group "html_url": "http://example.com/appointment_groups/1", // When the appointment group was created "created_at": "2012-07-13T10:55:20-06:00", // When the appointment group was last updated "updated_at": "2012-07-13T10:55:20-06:00" } ``` ## [List appointment groups](#method.appointment_groups.index) [AppointmentGroupsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups` **Scope:** `url:GET|/api/v1/appointment_groups` Retrieve the paginated list of appointment groups that can be reserved or managed by the current user. #### Request Parameters: | Parameter | Type | Description | | --------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `scope` | `string` | Defaults to "reservable" Allowed values: `reservable`, `manageable` | | `context_codes[]` | `string` | Array of context codes used to limit returned results. | | `include_past_appointments` | `boolean` | Defaults to false. If true, includes past appointment groups | | `include[]` | `string` | Array of additional information to include."appointments":: calendar event time slots for this appointment group"child\_events":: reservations of those time slots"participant\_count":: number of reservations"reserved\_times":: the event id, start time and end time of reservationsthe current user has made)"all\_context\_codes":: all context codes associated with this appointment group Allowed values: appointments, child\_events, participant\_count, reserved\_times, all\_context\_codes | ## [Create an appointment group](#method.appointment_groups.create) [AppointmentGroupsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `POST /api/v1/appointment_groups` **Scope:** `url:POST|/api/v1/appointment_groups` Create and return a new appointment group. If new\_appointments are specified, the response will return a new\_appointments array (same format as appointments array, see "List appointment groups" action) #### Request Parameters: | Parameter | Type | Description | | ----------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `appointment_group[context_codes][]` | Required `string` | Array of context codes (courses, e.g. course\_1) this group should belinked to (1 or more). Users in the course(s) with appropriate permissionswill be able to sign up for this appointment group. | | `appointment_group[sub_context_codes][]` | `string` | Array of sub context codes (course sections or a single group category)this group should be linked to. Used to limit the appointment group toparticular sections. If a group category is specified, students will signup in groups and the participant\_type will be "Group" instead of "User". | | `appointment_group[title]` | Required `string` | Short title for the appointment group. | | `appointment_group[description]` | `string` | Longer text description of the appointment group. | | `appointment_group[location_name]` | `string` | Location name of the appointment group. | | `appointment_group[location_address]` | `string` | Location address. | | `appointment_group[publish]` | `boolean` | Indicates whether this appointment group should be published (i.e. madeavailable for signup). Once published, an appointment group cannot beunpublished. Defaults to false. | | `appointment_group[participants_per_appointment]` | `integer` | Maximum number of participants that may register for each time slot.Defaults to null (no limit). | | `appointment_group[min_appointments_per_participant]` | `integer` | Minimum number of time slots a user must register for. If not set, usersdo not need to sign up for any time slots. | | `appointment_group[max_appointments_per_participant]` | `integer` | Maximum number of time slots a user may register for. | | `appointment_group[new_appointments][X][]` | `string` | Nested array of start time/end time pairs indicating time slots for thisappointment group. Refer to the example request. | | `appointment_group[participant_visibility]` | `string` | "private":: participants cannot see who has signed up for a particulartime slot"protected":: participants can see who has signed up. Defaults to"private". Allowed values: private, protected | | `appointment_group[allow_observer_signup]` | `boolean` | Whether observer users can sign-up for an appointment. Defaults to false. | #### Example Request: ```bash curl 'https:///api/v1/appointment_groups.json' \ -X POST \ -F 'appointment_group[context_codes][]=course_123' \ -F 'appointment_group[sub_context_codes][]=course_section_234' \ -F 'appointment_group[title]=Final Presentation' \ -F 'appointment_group[participants_per_appointment]=1' \ -F 'appointment_group[min_appointments_per_participant]=1' \ -F 'appointment_group[max_appointments_per_participant]=1' \ -F 'appointment_group[new_appointments][0][]=2012-07-19T21:00:00Z' \ -F 'appointment_group[new_appointments][0][]=2012-07-19T22:00:00Z' \ -F 'appointment_group[new_appointments][1][]=2012-07-19T22:00:00Z' \ -F 'appointment_group[new_appointments][1][]=2012-07-19T23:00:00Z' \ -H "Authorization: Bearer " ``` ## [Get a single appointment group](#method.appointment_groups.show) [AppointmentGroupsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups/:id` **Scope:** `url:GET|/api/v1/appointment_groups/:id` Returns information for a single appointment group #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Array of additional information to include. See include\[] argument of"List appointment groups" action."child\_events":: reservations of time slots time slots"appointments":: will always be returned"all\_context\_codes":: all context codes associated with this appointment group Allowed values: child\_events, appointments, all\_context\_codes | ## [Update an appointment group](#method.appointment_groups.update) [AppointmentGroupsController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `PUT /api/v1/appointment_groups/:id` **Scope:** `url:PUT|/api/v1/appointment_groups/:id` Update and return an appointment group. If new\_appointments are specified, the response will return a new\_appointments array (same format as appointments array, see "List appointment groups" action). #### Request Parameters: | Parameter | Type | Description | | ----------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `appointment_group[context_codes][]` | Required `string` | Array of context codes (courses, e.g. course\_1) this group should belinked to (1 or more). Users in the course(s) with appropriate permissionswill be able to sign up for this appointment group. | | `appointment_group[sub_context_codes][]` | `string` | Array of sub context codes (course sections or a single group category)this group should be linked to. Used to limit the appointment group toparticular sections. If a group category is specified, students will signup in groups and the participant\_type will be "Group" instead of "User". | | `appointment_group[title]` | `string` | Short title for the appointment group. | | `appointment_group[description]` | `string` | Longer text description of the appointment group. | | `appointment_group[location_name]` | `string` | Location name of the appointment group. | | `appointment_group[location_address]` | `string` | Location address. | | `appointment_group[publish]` | `boolean` | Indicates whether this appointment group should be published (i.e. madeavailable for signup). Once published, an appointment group cannot beunpublished. Defaults to false. | | `appointment_group[participants_per_appointment]` | `integer` | Maximum number of participants that may register for each time slot.Defaults to null (no limit). | | `appointment_group[min_appointments_per_participant]` | `integer` | Minimum number of time slots a user must register for. If not set, usersdo not need to sign up for any time slots. | | `appointment_group[max_appointments_per_participant]` | `integer` | Maximum number of time slots a user may register for. | | `appointment_group[new_appointments][X][]` | `string` | Nested array of start time/end time pairs indicating time slots for thisappointment group. Refer to the example request. | | `appointment_group[participant_visibility]` | `string` | "private":: participants cannot see who has signed up for a particulartime slot"protected":: participants can see who has signed up. Defaults to "private". Allowed values: private, protected | | `appointment_group[allow_observer_signup]` | `boolean` | Whether observer users can sign-up for an appointment. | #### Example Request: ```bash curl 'https:///api/v1/appointment_groups/543.json' \ -X PUT \ -F 'appointment_group[publish]=1' \ -H "Authorization: Bearer " ``` ## [Delete an appointment group](#method.appointment_groups.destroy) [AppointmentGroupsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `DELETE /api/v1/appointment_groups/:id` **Scope:** `url:DELETE|/api/v1/appointment_groups/:id` Delete an appointment group (and associated time slots and reservations) and return the deleted group #### Request Parameters: | Parameter | Type | Description | | --------------- | -------- | ---------------------------------------------------- | | `cancel_reason` | `string` | Reason for deleting/canceling the appointment group. | #### Example Request: ```bash curl 'https:///api/v1/appointment_groups/543.json' \ -X DELETE \ -F 'cancel_reason=El Tigre Chino got fired' \ -H "Authorization: Bearer " ``` ## [List user participants](#method.appointment_groups.users) [AppointmentGroupsController#users](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups/:id/users` **Scope:** `url:GET|/api/v1/appointment_groups/:id/users` A paginated list of users that are (or may be) participating in this appointment group. Refer to the Users API for the response fields. Returns no results for appointment groups with the "Group" participant\_type. #### Request Parameters: | Parameter | Type | Description | | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `registration_status` | `string` | Limits results to the a given participation status, defaults to "all" Allowed values: `all`, `registered`, `registered` | ## [List student group participants](#method.appointment_groups.groups) [AppointmentGroupsController#groups](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups/:id/groups` **Scope:** `url:GET|/api/v1/appointment_groups/:id/groups` A paginated list of student groups that are (or may be) participating in this appointment group. Refer to the Groups API for the response fields. Returns no results for appointment groups with the "User" participant\_type. #### Request Parameters: | Parameter | Type | Description | | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `registration_status` | `string` | Limits results to the a given participation status, defaults to "all" Allowed values: `all`, `registered`, `registered` | ## [Get next appointment](#method.appointment_groups.next_appointment) [AppointmentGroupsController#next\_appointment](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups/next_appointment` **Scope:** `url:GET|/api/v1/appointment_groups/next_appointment` Return the next appointment available to sign up for. The appointment is returned in a one-element array. If no future appointments are available, an empty array is returned. #### Request Parameters: | Parameter | Type | Description | | ------------------------- | -------- | -------------------------------------------- | | `appointment_group_ids[]` | `string` | List of ids of appointment groups to search. | Returns a list of [CalendarEvent](/services/canvas/resources/calendar_events#calendarevent) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Assessment Question Banks #### An AssessmentQuestionBank object looks like: ```js { // The ID of the assessment question bank. "id": 1, // The ID of the context (course or account) the question bank belongs to. "context_id": 2, // The type of context (Course or Account). "context_type": "Course", // The title of the question bank. "title": "Chapter 1 Questions", // The workflow state of the question bank. "workflow_state": "active", // The number of questions in the bank. "assessment_question_count": 10, // The combined context type and ID. "context_code": "course_2", // The date and time the question bank was created. "created_at": "2013-01-01T00:00:00Z", // The date and time the question bank was last updated. "updated_at": "2013-01-01T00:00:00Z" } ``` #### An AssessmentQuestion object looks like: ```js { // The ID of the assessment question. "id": 1, // The order of the question. "position": 1, // The ID of the question bank this question belongs to. "assessment_question_bank_id": 3, // The date and time when the assessment question was created. "created_at": "2013-01-23T23:59:00-07:00", // The name of the question. "question_name": "Prime Number Identification", // The type of the question. "question_type": "multiple_choice_question", // The text of the question. "question_text": "Which of the following is NOT a prime number?", // The maximum amount of points possible received for getting this question // correct. "points_possible": 5, // The comments to display if the student answers the question correctly. "correct_comments": "That's correct!", // The comments to display if the student answers incorrectly. "incorrect_comments": "Unfortunately, that IS a prime number.", // The comments to display regardless of how the student answered. "neutral_comments": "Goldbach's conjecture proposes that every even integer greater than 2 can be expressed as the sum of two prime numbers.", // The HTML version of the comments to display if the student answers the // question correctly. "correct_comments_html": "That's correct!", // The HTML version of the comments to display if the student answers // incorrectly. "incorrect_comments_html": "Unfortunately, that IS a prime number.", // The HTML version of the comments to display regardless of how the student // answered. "neutral_comments_html": "Goldbach's conjecture proposes that every even integer greater than 2 can be expressed as the sum of two prime numbers.", // An array of available answers. Each answer contains id, text, html, comments, // comments_html, and weight properties. "answers": null, // Variables for calculated questions. Null for other question types. "variables": null, // Formulas for calculated questions. Null for other question types. "formulas": null, // The tolerance for numerical answers. Null for non-numerical question types. "answer_tolerance": null, // The number of decimal places for formula results. Null for non-calculated // question types. "formula_decimal_places": null, // Matching pairs for matching questions. Null for other question types. "matches": null, // Incorrect match options for matching questions. Null for other question // types. "matching_answer_incorrect_matches": null } ``` ## [List question banks](#method.assessment_question_banks.index) [AssessmentQuestionBanksController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assessment_question_banks_controller.rb) #### `GET /api/v1/question_banks` **Scope:** `url:GET|/api/v1/question_banks` Returns the paginated list of question banks for a given context. #### Request Parameters: | Parameter | Type | Description | | ------------------------ | ------------------ | ---------------------------------------------------------------------------------------------- | | `context_type` | Required `string` | The type of context. Must be either "Course" or "Account". Allowed values: `Course`, `Account` | | `context_id` | Required `integer` | The id of the context. | | `include_question_count` | `boolean` | Whether to include the number of questions in each bank. | #### Example Request: ```bash curl 'https:///api/v1/question_banks?context_type=Course&context_id=1' \ -H 'Authorization: Bearer ' ``` Returns a list of [AssessmentQuestionBank](#assessmentquestionbank) objects. ## [Get a single question bank](#method.assessment_question_banks.show) [AssessmentQuestionBanksController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assessment_question_banks_controller.rb) #### `GET /api/v1/question_banks/:id` **Scope:** `url:GET|/api/v1/question_banks/:id` Returns the question bank with the given id #### Request Parameters: | Parameter | Type | Description | | ------------------------ | ------------------ | ------------------------------------------------------- | | `id` | Required `integer` | The question bank unique identifier. | | `include_question_count` | `boolean` | Whether to include the number of questions in the bank. | Returns an [AssessmentQuestionBank](#assessmentquestionbank) object. ## [List assessment questions for a question bank](#method.assessment_question_banks.questions) [AssessmentQuestionBanksController#questions](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assessment_question_banks_controller.rb) #### `GET /api/v1/question_banks/:id/questions` **Scope:** `url:GET|/api/v1/question_banks/:id/questions` Returns the paginated list of assessment questions in this bank. #### Request Parameters: | Parameter | Type | Description | | --------- | ------------------ | ------------------------------------ | | `id` | Required `integer` | The question bank unique identifier. | #### Example Request: ```bash curl 'https:///api/v1/question_banks/:id/questions' \ -H 'Authorization: Bearer ' ``` Returns a list of [AssessmentQuestion](#assessmentquestion) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Asset Processor 1EdTech Asset Processor services: Asset Service and Asset Report Service. 1EdTech Asset Processor services: Eula Service and Eula Acceptance Service. ## [Create an Asset Report](#method.lti/ims/asset_processor.create_report) [Lti::Ims::AssetProcessorController#create\_report](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/ims/asset_processor_controller.rb) #### `POST /api/lti/asset_processors/:asset_processor_id/reports` **Scope:** `url:POST|/api/lti/asset_processors/:asset_processor_id/reports` Creates a report for a given Canvas-managed asset (such as a submission attachment). Returns an HTTP 201 (Created) on success. #### Request Parameters: | Parameter | Type | Description | | -------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `assetId` | `string` | The UUID of the asset to which the report applies. Canvas will supplythis to the tool in the the LtiAssetProcessorSubmissionNotice. | | `errorCode` | `string` | A machine-readable code indicating the cause of the failure, for reportswith a processingProgress value of Failed. The following standard errorcodes are available, but tools may use their own (in which case the toolmay provide human-readable information in the comment field):UNSUPPORTED\_ASSET\_TYPE, ASSET\_TOO\_LARGE, ASSET\_TOO\_SMALL,EULA\_NOT\_ACCEPTED, DOWNLOAD\_FAILED | | `indicationAlt` | `string` | Alternate text representing the meaning of the indicationColor for screenreaders or as a tooltip over the indication color. | | `indicationColor` | `string` | A hex (#RRGGBB) color code the tool wishes to use indicating the outcomeof an asset's report. | | `priority` | `integer` | A number from 0 (meaning "good" or "success") to 5 (meaning urgent ortime-critical notable features) indicating the tool's perceived priorityof the report. If a priority is not known or applicable, the tool shoulduse the value 0. | | `processingProgress` | `string` | Indicates the status of the report. Should be one of the following:Processed, Processing, PendingManual, Failed, NotProcessed, NotReady.If an unrecognized value is given, the value will be stored, but willbe treated by Canvas as NotReady. | | `result` | `string` | A short string (16 characters or fewer) that briefly describes thesuccessful result of the processing. This should be provided ifprocessingProgress is Processed, and not provided otherwise. | | `timestamp` | `string` | An ISO8601 date time value with microsecond precision. Reports with newertimestamps for the same asset and report type supersedepreviously submitted reports with older (or equal) timestamps. Likewise,if the timestamp provided is older than the latest timestamp for anexisting report (of same asset and type), the new report will beignored and the endpoint will return an HTTP 409 (Conflict). | | `title` | `string` | A human-readable title for the report, to be displayed to the user. | | `type` | `string` | An opaque value representing the type of report. | | `visibleToOwner` | `boolean` | A boolean value indicates whether the indicator and reportshould be visible to the user who owns the asset being reported on.If no value is provided, the platform should assume a default value of false | #### Example Request: ```bash { "assetId" : "57d463ea-6e5d-45c8-a86f-64f3dd9ef81e", "type": "originality", "timestamp": "2025-01-24T17:56:53.221+00:00", "title": "Originality Report", "result" : "75/100", "indicationColor" : "#EC0000", "indicationAlt" : "High percentage of matched text.", "priority": 5, "processingProgress": "Processed" } ``` ```bash { "assetId" : "57d463ea-6e5d-45c8-a86f-64f3dd9ef81e", "type": "originality", "timestamp": "2025-01-24T17:56:53.221+00:00", "title": "Originality Report", "priority": 0, "errorCode": "UNSUPPORTED_ASSET_TYPE", "processingProgress": "Failed" } ``` #### Example Response: ```js { "assetId" : "57d463ea-6e5d-45c8-a86f-64f3dd9ef81e", "type": "originality", "timestamp": "2025-01-24T17:56:53.221+00:00", "title": "Originality Report", "result" : "75/100", "indicationColor" : "#EC0000", "indicationAlt" : "High percentage of matched text.", "priority": 5, "processingProgress": "Processed" } ``` ## [Update Eula Deployment Configuration](#method.lti/ims/asset_processor_eula.update_tool_eula) [Lti::Ims::AssetProcessorEulaController#update\_tool\_eula](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/ims/asset_processor_eula_controller.rb) #### `PUT /api/lti/asset_processor_eulas/:context_external_tool_id/deployment` **Scope:** `url:PUT|/api/lti/asset_processor_eulas/:context_external_tool_id/deployment` Provides a mechanism by which a platform can enable or disable the requirement for users to accept a EULA within the scope of an entire deployment #### Request Parameters: | Parameter | Type | Description | | -------------- | --------- | ------------------------------------------------------------------------------------ | | `eulaRequired` | `boolean` | A boolean value representing whether or not the EULA is required for the deployment. | #### Example Request: ```bash { "eulaRequired": true, } ``` #### Example Response: ```js { "eulaRequired": true, } ``` ## [Create an Eula Acceptance](#method.lti/ims/asset_processor_eula.create_acceptance) [Lti::Ims::AssetProcessorEulaController#create\_acceptance](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/ims/asset_processor_eula_controller.rb) #### `POST /api/lti/asset_processor_eulas/:context_external_tool_id/user` **Scope:** `url:POST|/api/lti/asset_processor_eulas/:context_external_tool_id/user` The EULA user acceptance service provides a mechanism by which a tool can notify a platform of whether or not a user has accepted a EULA. #### Request Parameters: | Parameter | Type | Description | | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userId` | `string` | The userId represents the user who has accepted or declined the EULA,lti\_id of the Canvas User. | | `accepted` | `boolean` | A boolean value representing whether or not the user has accepted the EULA | | `timestamp` | `string` | The timestamp represents the time at which the user accepted or declined the EULA.This timestamp must be formatted as an ISO 8601 date time. | #### Example Request: ```bash { "userId": "59ed2101-0302-406c-b53f-9705ae1cb357", "accepted": true, "timestamp": "2022-04-16T18:54:36.736+00:00" } ``` #### Example Response: ```js { "userId": "59ed2101-0302-406c-b53f-9705ae1cb357", "accepted": true, "timestamp": "2022-04-16T18:54:36.736+00:00" } ``` ## [Delete Eula Acceptances for deployment](#method.lti/ims/asset_processor_eula.delete_acceptances) [Lti::Ims::AssetProcessorEulaController#delete\_acceptances](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/ims/asset_processor_eula_controller.rb) #### `DELETE /api/lti/asset_processor_eulas/:context_external_tool_id/user` **Scope:** `url:DELETE|/api/lti/asset_processor_eulas/:context_external_tool_id/user` Remove the EULA acceptance status for all users within the current deployment. This will allow a tool to reset the EULA acceptance status for all users, and force them to accept the EULA again in the case that the EULA has changed. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Assignment Extensions API for setting extensions on student assignment submissions. These cannot be set for discussion assignments or quizzes. For quizzes, use [Quiz Extensions](/services/canvas/resources/quiz_extensions) instead. #### An AssignmentExtension object looks like: ```js { // The ID of the Assignment the extension belongs to. "assignment_id": 2, // The ID of the Student that needs the assignment extension. "user_id": 3, // Number of times the student is allowed to re-submit the assignment "extra_attempts": 2 } ``` ## [Set extensions for student assignment submissions](#method.assignment_extensions.create) [AssignmentExtensionsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_extensions_controller.rb) #### `POST /api/v1/courses/:course_id/assignments/:assignment_id/extensions` **Scope:** `url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/extensions` \Responses\ * \200 OK\ if the request was successful * \403 Forbidden\ if you are not allowed to extend assignments for this course * \400 Bad Request\ if any of the extensions are invalid #### Request Parameters: | Parameter | Type | Description | | ----------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------ | | `assignment_extensions[][user_id]` | Required `integer` | The ID of the user we want to add assignment extensions for. | | `assignment_extensions[][extra_attempts]` | Required `integer` | Number of times the student is allowed to re-take the assignment over thelimit. | #### Example Request: ```bash { "assignment_extensions": [{ "user_id": 3, "extra_attempts": 2 },{ "user_id": 2, "extra_attempts": 2 }] } ``` #### Example Response: ```js { "assignment_extensions": [AssignmentExtension] } ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Assignment Groups API for accessing Assignment Group and Assignment information. #### A GradingRules object looks like: ```js { // Number of lowest scores to be dropped for each user. "drop_lowest": 1, // Number of highest scores to be dropped for each user. "drop_highest": 1, // Assignment IDs that should never be dropped. "never_drop": [33, 17, 24] } ``` #### An AssignmentGroup object looks like: ```js { // the id of the Assignment Group "id": 1, // the name of the Assignment Group "name": "group2", // the position of the Assignment Group "position": 7, // the weight of the Assignment Group "group_weight": 20, // the sis source id of the Assignment Group "sis_source_id": "1234", // the integration data of the Assignment Group "integration_data": {"5678":"0954"}, // the assignments in this Assignment Group (see the Assignment API for a // detailed list of fields) "assignments": [], // the grading rules that this Assignment Group has "rules": null } ``` ## [List assignment groups](#method.assignment_groups.index) [AssignmentGroupsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_controller.rb) #### `GET /api/v1/courses/:course_id/assignment_groups` **Scope:** `url:GET|/api/v1/courses/:course_id/assignment_groups` Returns the paginated list of assignment groups for the current context. The returned groups are sorted by their position field. #### Request Parameters: | Parameter | Type | Description | | --------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `include[]` | `string` | Associations to include with the group. "discussion\_topic", "all\_dates", "can\_edit","assignment\_visibility" & "submission" are only valid if "assignments" is also included."score\_statistics" requires that the "assignments" and "submission" options are included.The "assignment\_visibility" option additionally requires that the Differentiated Assignments course feature be turned on.If "observed\_users" is passed along with "assignments" and "submission", submissions for observed users will also be included as an array.The "peer\_review" option requires that the Peer Review Grading course feature be turned on and that "assignments" is included. Allowed values: assignments, discussion\_topic, all\_dates, assignment\_visibility, overrides, submission, observed\_users, can\_edit, score\_statistics, peer\_review | | `assignment_ids[]` | `string` | If "assignments" are included, optionally return only assignments having their ID in this array. This argument may also be passed asa comma separated string. | | `exclude_assignment_submission_types[]` | `string` | If "assignments" are included, those with the specified submission typeswill be excluded from the assignment groups. Allowed values: online\_quiz, discussion\_topic, wiki\_page, external\_tool | | `override_assignment_dates` | `boolean` | Apply assignment overrides for each assignment, defaults to true. | | `grading_period_id` | `integer` | The id of the grading period in which assignment groups are being requested(Requires grading periods to exist.) | | `scope_assignments_to_student` | `boolean` | If true, all assignments returned will apply to the current user in thespecified grading period. If assignments apply to other students in thespecified grading period, but not the current user, they will not bereturned. (Requires the grading\_period\_id argument and grading periods toexist. In addition, the current user must be a student.) | Returns a list of [AssignmentGroup](#assignmentgroup) objects. ## [Get an Assignment Group](#method.assignment_groups_api.show) [AssignmentGroupsApiController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_api_controller.rb) #### `GET /api/v1/courses/:course_id/assignment_groups/:assignment_group_id` **Scope:** `url:GET|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id` Returns the assignment group with the given id. #### Request Parameters: | Parameter | Type | Description | | --------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Associations to include with the group. "discussion\_topic" and "assignment\_visibility" and "submission"are only valid if "assignments" is also included. "score\_statistics" is only valid if "submission" and"assignments" are also included. The "assignment\_visibility" option additionally requires that the Differentiated Assignmentscourse feature be turned on. Allowed values: assignments, discussion\_topic, assignment\_visibility, submission, score\_statistics | | `override_assignment_dates` | `boolean` | Apply assignment overrides for each assignment, defaults to true. | | `grading_period_id` | `integer` | The id of the grading period in which assignment groups are being requested(Requires grading periods to exist on the account) | Returns an [AssignmentGroup](#assignmentgroup) object. ## [Create an Assignment Group](#method.assignment_groups_api.create) [AssignmentGroupsApiController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_api_controller.rb) #### `POST /api/v1/courses/:course_id/assignment_groups` **Scope:** `url:POST|/api/v1/courses/:course_id/assignment_groups` Create a new assignment group for this course. #### Request Parameters: | Parameter | Type | Description | | ------------------ | --------- | -------------------------------------------------------------------------------- | | `name` | `string` | The assignment group's name | | `position` | `integer` | The position of this assignment group in relation to the other assignment groups | | `group_weight` | `number` | The percent of the total grade that this assignment group represents | | `sis_source_id` | `string` | The sis source id of the Assignment Group | | `integration_data` | `Object` | The integration data of the Assignment Group | Returns an [AssignmentGroup](#assignmentgroup) object. ## [Edit an Assignment Group](#method.assignment_groups_api.update) [AssignmentGroupsApiController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_api_controller.rb) #### `PUT /api/v1/courses/:course_id/assignment_groups/:assignment_group_id` **Scope:** `url:PUT|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id` Modify an existing Assignment Group. #### Request Parameters: | Parameter | Type | Description | | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | The assignment group's name | | `position` | `integer` | The position of this assignment group in relation to the other assignment groups | | `group_weight` | `number` | The percent of the total grade that this assignment group represents | | `sis_source_id` | `string` | The sis source id of the Assignment Group | | `integration_data` | `Object` | The integration data of the Assignment Group | | `rules` | `string` | The grading rules that are applied within this assignment groupSee the Assignment Group object definition for format | Returns an [AssignmentGroup](#assignmentgroup) object. ## [Destroy an Assignment Group](#method.assignment_groups_api.destroy) [AssignmentGroupsApiController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_api_controller.rb) #### `DELETE /api/v1/courses/:course_id/assignment_groups/:assignment_group_id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id` Deletes the assignment group with the given id. #### Request Parameters: | Parameter | Type | Description | | --------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `move_assignments_to` | `integer` | The ID of an active Assignment Group to which the assignments that arecurrently assigned to the destroyed Assignment Group will be assigned.NOTE: If this argument is not provided, any assignments in this AssignmentGroup will be deleted. | Returns an [AssignmentGroup](#assignmentgroup) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Assignments API for accessing assignment information. #### An ExternalToolTagAttributes object looks like: ```js { // URL to the external tool "url": "http://instructure.com", // Whether or not there is a new tab for the external tool "new_tab": false, // the identifier for this tool_tag "resource_link_id": "ab81173af98b8c33e66a" } ``` #### A LockInfo object looks like: ```js { // Asset string for the object causing the lock "asset_string": "assignment_4", // (Optional) Time at which this was/will be unlocked. Must be before the due // date. "unlock_at": "2013-01-01T00:00:00-06:00", // (Optional) Time at which this was/will be locked. Must be after the due date. "lock_at": "2013-02-01T00:00:00-06:00", // (Optional) Context module causing the lock. "context_module": "{}", "manually_locked": true } ``` #### A RubricRating object looks like: ```js { "points": 10, "id": "rat1", "description": "Full marks", "long_description": "Student completed the assignment flawlessly." } ``` #### A RubricCriteria object looks like: ```js { "points": 10, // The id of rubric criteria. "id": "crit1", // (Optional) The id of the learning outcome this criteria uses, if any. "learning_outcome_id": "1234", // (Optional) The 3rd party vendor's GUID for the outcome this criteria // references, if any. "vendor_guid": "abdsfjasdfne3jsdfn2", "description": "Criterion 1", "long_description": "Criterion 1 more details", "criterion_use_range": true, "ratings": null, "ignore_for_scoring": true } ``` #### An AssignmentDate object looks like: ```js // Object representing a due date for an assignment or quiz. If the due date // came from an assignment override, it will have an 'id' field. { // (Optional, missing if 'base' is present) id of the assignment override this // date represents "id": 1, // (Optional, present if 'id' is missing) whether this date represents the // assignment's or quiz's default due date "base": true, "title": "Summer Session", // The due date for the assignment. Must be between the unlock date and the lock // date if there are lock dates "due_at": "2013-08-28T23:59:00-06:00", // The unlock date for the assignment. Must be before the due date if there is a // due date. "unlock_at": "2013-08-01T00:00:00-06:00", // The lock date for the assignment. Must be after the due date if there is a // due date. "lock_at": "2013-08-31T23:59:00-06:00" } ``` #### A TurnitinSettings object looks like: ```js { "originality_report_visibility": "after_grading", "s_paper_check": false, "internet_check": false, "journal_check": false, "exclude_biblio": false, "exclude_quoted": false, "exclude_small_matches_type": "percent", "exclude_small_matches_value": 50 } ``` #### A NeedsGradingCount object looks like: ```js // Used by Assignment model { // The section ID "section_id": "123456", // Number of submissions that need grading "needs_grading_count": 5 } ``` #### A ScoreStatistic object looks like: ```js // Used by Assignment model { // Min score "min": 1, // Max score "max": 10, // Mean score "mean": 6, // Upper quartile score "upper_q": 10, // Median score "median": 6, // Lower quartile score "lower_q": 1 } ``` #### An Assignment object looks like: ```js { // the ID of the assignment "id": 4, // the name of the assignment "name": "some assignment", // the assignment description, in an HTML fragment "description": "Do the following:...", // The time at which this assignment was originally created "created_at": "2012-07-01T23:59:00-06:00", // The time at which this assignment was last modified in any way "updated_at": "2012-07-01T23:59:00-06:00", // the due date for the assignment. returns null if not present. NOTE: If this // assignment has assignment overrides, this field will be the due date as it // applies to the user requesting information from the API. "due_at": "2012-07-01T23:59:00-06:00", // the lock date (assignment is locked after this date). returns null if not // present. NOTE: If this assignment has assignment overrides, this field will // be the lock date as it applies to the user requesting information from the // API. "lock_at": "2012-07-01T23:59:00-06:00", // the unlock date (assignment is unlocked after this date) returns null if not // present NOTE: If this assignment has assignment overrides, this field will be // the unlock date as it applies to the user requesting information from the // API. "unlock_at": "2012-07-01T23:59:00-06:00", // whether this assignment has overrides "has_overrides": true, // (Optional) all dates associated with the assignment, if applicable "all_dates": null, // the ID of the course the assignment belongs to "course_id": 123, // the URL to the assignment's web page "html_url": "https://...", // the URL to download all submissions as a zip "submissions_download_url": "https://example.com/courses/:course_id/assignments/:id/submissions?zip=1", // the ID of the assignment's group "assignment_group_id": 2, // Boolean flag indicating whether the assignment requires a due date based on // the account level setting "due_date_required": true, // Allowed file extensions, which take effect if submission_types includes // 'online_upload'. "allowed_extensions": ["docx", "ppt"], // An integer indicating the maximum length an assignment's name may be "max_name_length": 15, // Boolean flag indicating whether or not Turnitin has been enabled for the // assignment. NOTE: This flag will not appear unless your account has the // Turnitin plugin available "turnitin_enabled": true, // Boolean flag indicating whether or not VeriCite has been enabled for the // assignment. NOTE: This flag will not appear unless your account has the // VeriCite plugin available "vericite_enabled": true, // Settings to pass along to turnitin to control what kinds of matches should be // considered. originality_report_visibility can be 'immediate', // 'after_grading', 'after_due_date', or 'never' exclude_small_matches_type can // be null, 'percent', 'words' exclude_small_matches_value: - if type is null, // this will be null also - if type is 'percent', this will be a number between // 0 and 100 representing match size to exclude as a percentage of the document // size. - if type is 'words', this will be number > 0 representing how many // words a match must contain for it to be considered NOTE: This flag will not // appear unless your account has the Turnitin plugin available "turnitin_settings": null, // If this is a group assignment, boolean flag indicating whether or not // students will be graded individually. "grade_group_students_individually": false, // (Optional) assignment's settings for external tools if submission_types // include 'external_tool'. Only url and new_tab are included (new_tab defaults // to false). Use the 'External Tools' API if you need more information about // an external tool. "external_tool_tag_attributes": null, // Boolean indicating if peer reviews are required for this assignment "peer_reviews": false, // Boolean indicating peer reviews are assigned automatically. If false, the // teacher is expected to manually assign peer reviews. "automatic_peer_reviews": false, // Integer representing the amount of reviews each user is assigned. NOTE: This // key is NOT present unless you have automatic_peer_reviews set to true. "peer_review_count": 0, // String representing a date the reviews are due by. Must be a date that occurs // after the default due date. If blank, or date is not after the assignment's // due date, the assignment's due date will be used. NOTE: This key is NOT // present unless you have automatic_peer_reviews set to true. "peer_reviews_assign_at": "2012-07-01T23:59:00-06:00", // Boolean representing whether or not members from within the same group on a // group assignment can be assigned to peer review their own group's work "intra_group_peer_reviews": false, // The ID of the assignment’s group set, if this is a group assignment. For // group discussions, set group_category_id on the discussion topic, not the // linked assignment. "group_category_id": 1, // if the requesting user has grading rights, the number of submissions that // need grading. "needs_grading_count": 17, // if the requesting user has grading rights and the // 'needs_grading_count_by_section' flag is specified, the number of submissions // that need grading split out by section. NOTE: This key is NOT present unless // you pass the 'needs_grading_count_by_section' argument as true. ANOTHER // NOTE: it's possible to be enrolled in multiple sections, and if a student is // setup that way they will show an assignment that needs grading in multiple // sections (effectively the count will be duplicated between sections) "needs_grading_count_by_section": [{"section_id":"123456","needs_grading_count":5}, {"section_id":"654321","needs_grading_count":0}], // the sorting order of the assignment in the group "position": 1, // (optional, present if Sync Grades to SIS feature is enabled) "post_to_sis": true, // (optional, Third Party unique identifier for Assignment) "integration_id": "12341234", // (optional, Third Party integration data for assignment) "integration_data": {"5678":"0954"}, // the maximum points possible for the assignment "points_possible": 12.0, // the types of submissions allowed for this assignment list containing one or // more of the following: 'discussion_topic', 'online_quiz', 'on_paper', 'none', // 'external_tool', 'online_text_entry', 'online_url', 'online_upload', // 'media_recording', 'student_annotation' "submission_types": ["online_text_entry"], // If true, the assignment has been submitted to by at least one student "has_submitted_submissions": true, // The type of grading the assignment receives; one of 'pass_fail', 'percent', // 'letter_grade', 'gpa_scale', 'points' "grading_type": "points", // The id of the grading standard being applied to this assignment. Valid if // grading_type is 'letter_grade' or 'gpa_scale'. "grading_standard_id": null, // Whether the assignment is published "published": true, // Whether the assignment's 'published' state can be changed to false. Will be // false if there are student submissions for the assignment. "unpublishable": false, // Whether the assignment is only visible to overrides. "only_visible_to_overrides": false, // Whether or not this is locked for the user. "locked_for_user": false, // (Optional) Information for the user about the lock. Present when // locked_for_user is true. "lock_info": null, // (Optional) An explanation of why this is locked for the user. Present when // locked_for_user is true. "lock_explanation": "This assignment is locked until September 1 at 12:00am", // (Optional) id of the associated quiz (applies only when submission_types is // ['online_quiz']) "quiz_id": 620, // (Optional) whether anonymous submissions are accepted (applies only to quiz // assignments) "anonymous_submissions": false, // (Optional) the DiscussionTopic associated with the assignment, if applicable "discussion_topic": null, // (Optional) Boolean indicating if assignment will be frozen when it is copied. // NOTE: This field will only be present if the AssignmentFreezer plugin is // available for your account. "freeze_on_copy": false, // (Optional) Boolean indicating if assignment is frozen for the calling user. // NOTE: This field will only be present if the AssignmentFreezer plugin is // available for your account. "frozen": false, // (Optional) Array of frozen attributes for the assignment. Only account // administrators currently have permission to change an attribute in this list. // Will be empty if no attributes are frozen for this assignment. Possible // frozen attributes are: title, description, lock_at, points_possible, // grading_type, submission_types, assignment_group_id, allowed_extensions, // group_category_id, notify_of_update, peer_reviews NOTE: This field will only // be present if the AssignmentFreezer plugin is available for your account. "frozen_attributes": ["title"], // (Optional) If 'submission' is included in the 'include' parameter, includes a // Submission object that represents the current user's (user who is requesting // information from the api) current submission for the assignment. See the // Submissions API for an example response. If the user does not have a // submission, this key will be absent. "submission": null, // (Optional) If true, the rubric is directly tied to grading the assignment. // Otherwise, it is only advisory. Included if there is an associated rubric. "use_rubric_for_grading": true, // (Optional) An object describing the basic attributes of the rubric, including // the point total. Included if there is an associated rubric. "rubric_settings": {"points_possible":"12"}, // (Optional) A list of scoring criteria and ratings for each rubric criterion. // Included if there is an associated rubric. "rubric": null, // (Optional) If 'assignment_visibility' is included in the 'include' parameter, // includes an array of student IDs who can see this assignment. "assignment_visibility": [137, 381, 572], // (Optional) If 'overrides' is included in the 'include' parameter, includes an // array of assignment override objects. "overrides": null, // (Optional) If true, the assignment will be omitted from the student's final // grade "omit_from_final_grade": true, // (Optional) If true, the assignment will not be shown in any gradebooks "hide_in_gradebook": true, // Boolean indicating if the assignment is moderated. "moderated_grading": true, // The maximum number of provisional graders who may issue grades for this // assignment. Only relevant for moderated assignments. Must be a positive // value, and must be set to 1 if the course has fewer than two active // instructors. Otherwise, the maximum value is the number of active instructors // in the course minus one, or 10 if the course has more than 11 active // instructors. "grader_count": 3, // The user ID of the grader responsible for choosing final grades for this // assignment. Only relevant for moderated assignments. "final_grader_id": 3, // Boolean indicating if provisional graders' comments are visible to other // provisional graders. Only relevant for moderated assignments. "grader_comments_visible_to_graders": true, // Boolean indicating if provisional graders' identities are hidden from other // provisional graders. Only relevant for moderated assignments with // grader_comments_visible_to_graders set to true. "graders_anonymous_to_graders": true, // Boolean indicating if provisional grader identities are visible to the final // grader. Only relevant for moderated assignments. "grader_names_visible_to_final_grader": true, // Boolean indicating if the assignment is graded anonymously. If true, graders // cannot see student identities. "anonymous_grading": true, // The number of submission attempts a student can make for this assignment. -1 // is considered unlimited. "allowed_attempts": 2, // Whether the assignment has manual posting enabled. Only relevant for courses // using New Gradebook. "post_manually": true, // (Optional) If 'score_statistics' and 'submission' are included in the // 'include' parameter and statistics are available, includes the min, max, and // mode for this assignment "score_statistics": null, // (Optional) If retrieving a single assignment and 'can_submit' is included in // the 'include' parameter, flags whether user has the right to submit the // assignment (i.e. checks enrollment dates, submission types, locked status, // attempts remaining, etc...). Including 'can submit' automatically includes // 'submission' in the include parameter. Not available when observed_users are // included. "can_submit": true, // (Optional) The academic benchmark(s) associated with the assignment or the // assignment's rubric. Only included if 'ab_guid' is included in the 'include' // parameter. "ab_guid": ["ABCD", "EFGH"], // (Optional) The account-level academic integrity pledge text a student must // accept before submitting this assignment. Only present if // 'academic_integrity_pledge' is included in the 'include' parameter AND the // pledge is enabled for the account; otherwise the key is omitted. When present // but the pledge does not apply to this particular assignment (e.g. external // tool assignments or Canvas Career courses), the value is null. "academic_integrity_pledge": "This submission reflects my own ideas and work", // The id of the attachment to be annotated by students. Relevant only if // submission_types includes 'student_annotation'. "annotatable_attachment_id": null, // (Optional) Boolean indicating whether student names are anonymized "anonymize_students": false, // (Optional) Boolean indicating whether the Respondus LockDown Browser® is // required for this assignment. "require_lockdown_browser": false, // (Optional) Boolean indicating whether this assignment has important dates. "important_dates": false, // (Optional, Deprecated) Boolean indicating whether notifications are muted for // this assignment. "muted": false, // Boolean indicating whether peer reviews are anonymous. "anonymous_peer_reviews": false, // Boolean indicating whether instructor anotations are anonymous. "anonymous_instructor_annotations": false, // Boolean indicating whether this assignment has graded submissions. "graded_submissions_exist": false, // Boolean indicating whether this is a quiz lti assignment. "is_quiz_assignment": false, // Boolean indicating whether this assignment is in a closed grading period. "in_closed_grading_period": false, // Boolean indicating whether this assignment can be duplicated. "can_duplicate": false, // If this assignment is a duplicate, it is the original assignment's course_id "original_course_id": 4, // If this assignment is a duplicate, it is the original assignment's id "original_assignment_id": 4, // If this assignment is a duplicate, it is the original assignment's // lti_resource_link_id "original_lti_resource_link_id": 4, // If this assignment is a duplicate, it is the original assignment's name "original_assignment_name": "some assignment", // If this assignment is a duplicate, it is the original assignment's quiz_id "original_quiz_id": 4, // String indicating what state this assignment is in. "workflow_state": "unpublished" } ``` #### A BasicUser object looks like: ```js { // The user's ID "id": "123456", // The user's name "name": "Dankey Kang" } ``` #### An AssignmentOverride object looks like: ```js { // the ID of the assignment override "id": 4, // the ID of the assignment the override applies to (present if the override // applies to an assignment) "assignment_id": 123, // the ID of the quiz the override applies to (present if the override applies // to a quiz) "quiz_id": 123, // the ID of the module the override applies to (present if the override applies // to a module) "context_module_id": 123, // the ID of the discussion the override applies to (present if the override // applies to an ungraded discussion) "discussion_topic_id": 123, // the ID of the page the override applies to (present if the override applies // to a page) "wiki_page_id": 123, // the ID of the file the override applies to (present if the override applies // to a file) "attachment_id": 123, // the IDs of the override's target students (present if the override targets an // ad-hoc set of students) "student_ids": [1, 2, 3], // the ID of the override's target group (present if the override targets a // group and the assignment is a group assignment) "group_id": 2, // the ID of the overrides's target section (present if the override targets a // section) "course_section_id": 1, // the title of the override "title": "an assignment override", // the overridden due at (present if due_at is overridden) "due_at": "2012-07-01T23:59:00-06:00", // the overridden all day flag (present if due_at is overridden) "all_day": true, // the overridden all day date (present if due_at is overridden) "all_day_date": "2012-07-01", // the overridden unlock at (present if unlock_at is overridden) "unlock_at": "2012-07-01T23:59:00-06:00", // the overridden lock at, if any (present if lock_at is overridden) "lock_at": "2012-07-01T23:59:00-06:00" } ``` ## [Delete an assignment](#method.assignments.destroy) [AssignmentsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_controller.rb) #### `DELETE /api/v1/courses/:course_id/assignments/:id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/assignments/:id` Delete the given assignment. #### Example Request: ```bash curl https:///api/v1/courses//assignments/ \ -X DELETE \ -H 'Authorization: Bearer ' ``` Returns an [Assignment](#assignment) object. ## [List assignments](#method.assignments_api.index) [AssignmentsApiController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `GET /api/v1/courses/:course_id/assignments` **Scope:** `url:GET|/api/v1/courses/:course_id/assignments` #### `GET /api/v1/courses/:course_id/assignment_groups/:assignment_group_id/assignments` **Scope:** `url:GET|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id/assignments` Returns the paginated list of assignments for the current course or assignment group. #### Request Parameters: | Parameter | Type | Description | | -------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Optional information to include with each assignment:submission:: The current user's current +Submission+assignment\_visibility:: An array of ids of students who can see the assignmentall\_dates:: An array of +AssignmentDate+ structures, one for each override, and also a +base+ if the assignment has an "Everyone" / "Everyone Else" dateoverrides:: An array of +AssignmentOverride+ structuresobserved\_users:: An array of submissions for observed userscan\_edit:: an extra Boolean value will be included with each +Assignment+ (and +AssignmentDate+ if +all\_dates+ is supplied) to indicate whether the caller can edit the assignment or date. Moderated grading and closed grading periods may restrict a user's ability to edit an assignment.score\_statistics:: An object containing min, max, and mean score on this assignment. This will not be included for students if there are less than 5 graded assignments or if disabled by the instructor. Only valid if 'submission' is also included.ab\_guid:: An array of guid strings for academic benchmarks Allowed values: submission, assignment\_visibility, all\_dates, overrides, observed\_users, can\_edit, score\_statistics, ab\_guid | | `search_term` | `string` | The partial title of the assignments to match and return. | | `override_assignment_dates` | `boolean` | Apply assignment overrides for each assignment, defaults to true. | | `needs_grading_count_by_section` | `boolean` | Split up "needs\_grading\_count" by sections into the "needs\_grading\_count\_by\_section" key, defaults to false | | `bucket` | `string` | If included, only return certain assignments depending on due date and submission status. Allowed values: `past`, `overdue`, `undated`, `ungraded`, `unsubmitted`, `upcoming`, `future` | | `assignment_ids[]` | `string` | if set, return only assignments specified | | `order_by` | `string` | Determines the order of the assignments. Defaults to "position". Allowed values: `position`, `name`, `due_at` | | `post_to_sis` | `boolean` | Return only assignments that have post\_to\_sis set or not set. | | `new_quizzes` | `boolean` | Return only New Quizzes assignments | Returns a list of [Assignment](#assignment) objects. ## [List assignments for user](#method.assignments_api.user_index) [AssignmentsApiController#user\_index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `GET /api/v1/users/:user_id/courses/:course_id/assignments` **Scope:** `url:GET|/api/v1/users/:user_id/courses/:course_id/assignments` Returns the paginated list of assignments for the specified user if the current user has rights to view. See [List assignments](#method.assignments_api.index) for valid arguments. ## [Duplicate assignment](#method.assignments_api.duplicate) [AssignmentsApiController#duplicate](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `POST /api/v1/courses/:course_id/assignments/:assignment_id/duplicate` **Scope:** `url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/duplicate` Duplicate an assignment and return a json based on result\_type argument. #### Request Parameters: | Parameter | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `result_type` | `string` | Optional information:When the root account has the feature newquizzes\_on\_quiz\_page enabledand this argument is set to "Quiz" the response will be serialized into aquiz format;When this argument isn't specified the response will be serialized into anassignment format; Allowed values: Quiz | #### Example Request: ```bash curl -X POST -H 'Authorization: Bearer ' \ https:///api/v1/courses/123/assignments/123/duplicate ``` ```bash curl -X POST -H 'Authorization: Bearer ' \ https:///api/v1/courses/123/assignments/123/duplicate?result_type=Quiz ``` Returns an [Assignment](#assignment) object. ## [List group members for a student on an assignment](#method.assignments_api.student_group_members) [AssignmentsApiController#student\_group\_members](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `GET /api/v1/courses/:course_id/assignments/:assignment_id/users/:user_id/group_members` **Scope:** `url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/users/:user_id/group_members` Returns student ids and names for the group. #### Example Request: ```bash curl https:///api/v1/courses/1/assignments/1/users/1/group_members ``` Returns a list of [BasicUser](#basicuser) objects. ## [Get a single assignment](#method.assignments_api.show) [AssignmentsApiController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `GET /api/v1/courses/:course_id/assignments/:id` **Scope:** `url:GET|/api/v1/courses/:course_id/assignments/:id` Returns the assignment with the given id. #### Request Parameters: | Parameter | Type | Description | | -------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Associations to include with the assignment. The "assignment\_visibility" optionrequires that the Differentiated Assignments course feature be turned on. If"observed\_users" is passed, submissions for observed users will also be included.For "score\_statistics" to be included, the "submission" option must also be set.The "peer\_review" option returns peer review sub assignment data if it exists, regardlessof the Peer Review Allocation and Grading feature state. If no peer review sub assignmentexists, the feature must be enabled to receive a null value; otherwise the key is omitted.The "academic\_integrity\_pledge" option returns the account-level academic integritypledge text a student must accept before submitting this assignment. The key is onlypresent when the pledge is enabled for the account; when present but the pledge does notapply to this assignment (e.g. external tool assignments or Canvas Career courses) thevalue is null. Allowed values: submission, assignment\_visibility, overrides, observed\_users, can\_edit, score\_statistics, ab\_guid, peer\_review, academic\_integrity\_pledge | | `override_assignment_dates` | `boolean` | Apply assignment overrides to the assignment, defaults to true. | | `needs_grading_count_by_section` | `boolean` | Split up "needs\_grading\_count" by sections into the "needs\_grading\_count\_by\_section" key, defaults to false | | `all_dates` | `boolean` | All dates associated with the assignment, if applicable | Returns an [Assignment](#assignment) object. ## [Create an assignment](#method.assignments_api.create) [AssignmentsApiController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `POST /api/v1/courses/:course_id/assignments` **Scope:** `url:POST|/api/v1/courses/:course_id/assignments` Create a new assignment for this course. The assignment is created in the active state. #### Request Parameters: | Parameter | Type | Description | | --------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `assignment[name]` | Required `string` | The assignment name. | | `assignment[position]` | `integer` | The position of this assignment in the group when displayingassignment lists. | | `assignment[submission_types][]` | `string` | List of supported submission types for the assignment.Unless the assignment is allowing online submissions, the array shouldonly have one element.If not allowing online submissions, your options are:"online\_quiz""none""on\_paper""discussion\_topic""external\_tool"If you are allowing online submissions, you can have one or manyallowed submission types:"online\_upload""online\_text\_entry""online\_url""media\_recording" (Only valid when the Kaltura plugin is enabled)"student\_annotation" Allowed values: online\_quiz, none, on\_paper, discussion\_topic, external\_tool, online\_upload, online\_text\_entry, online\_url, media\_recording, student\_annotation | | `assignment[allowed_extensions][]` | `string` | Allowed extensions if submission\_types includes "online\_upload"Example:allowed\_extensions: \["docx","ppt"] | | `assignment[turnitin_enabled]` | `boolean` | Only applies when the Turnitin plugin is enabled for a course andthe submission\_types array includes "online\_upload".Toggles Turnitin submissions for the assignment.Will be ignored if Turnitin is not available for the course. | | `assignment[vericite_enabled]` | `boolean` | Only applies when the VeriCite plugin is enabled for a course andthe submission\_types array includes "online\_upload".Toggles VeriCite submissions for the assignment.Will be ignored if VeriCite is not available for the course. | | `assignment[turnitin_settings]` | `string` | Settings to send along to turnitin. See Assignment object definition forformat. | | `assignment[integration_data]` | `string` | Data used for SIS integrations. Requires admin-level token with the "Manage SIS" permission. JSON string required. | | `assignment[integration_id]` | `string` | Unique ID from third party integrations | | `assignment[peer_reviews]` | `boolean` | If submission\_types does not include external\_tool,discussion\_topic,online\_quiz, or on\_paper, determines whether or not peer reviewswill be turned on for the assignment. | | `assignment[automatic_peer_reviews]` | `boolean` | Whether peer reviews will be assigned automatically by Canvas or ifteachers must manually assign peer reviews. Does not apply if peer reviewsare not enabled. | | `assignment[notify_of_update]` | `boolean` | If true, Canvas will send a notification to students in the classnotifying them that the content has changed. | | `assignment[group_category_id]` | `integer` | If present, the assignment will become a group assignment assignedto the group. | | `assignment[grade_group_students_individually]` | `integer` | If this is a group assignment, teachers have the options to gradestudents individually. If false, Canvas will apply the assignment'sscore to each member of the group. If true, the teacher can manuallyassign scores to each member of the group. | | `assignment[external_tool_tag_attributes]` | `string` | Hash of external tool parameters if submission\_types is \["external\_tool"].See Assignment object definition for format. | | `assignment[points_possible]` | `number` | The maximum points possible on the assignment. | | `assignment[grading_type]` | `string` | The strategy used for grading the assignment.The assignment defaults to "points" if this field is omitted. Allowed values: pass\_fail, percent, letter\_grade, gpa\_scale, points, not\_graded | | `assignment[due_at]` | `DateTime` | The day/time the assignment is due. Must be between the lock dates if there are lock dates.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[lock_at]` | `DateTime` | The day/time the assignment is locked after. Must be after the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[unlock_at]` | `DateTime` | The day/time the assignment is unlocked. Must be before the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[description]` | `string` | The assignment's description, supports HTML. | | `assignment[assignment_group_id]` | `integer` | The assignment group id to put the assignment in.Defaults to the top assignment group in the course. | | `assignment[assignment_overrides][]` | `AssignmentOverride` | List of overrides for the assignment. | | `assignment[only_visible_to_overrides]` | `boolean` | Whether this assignment is only visible to overrides(Only useful if 'differentiated assignments' account setting is on) | | `assignment[published]` | `boolean` | Whether this assignment is published.(Only useful if 'draft state' account setting is on)Unpublished assignments are not visible to students. | | `assignment[grading_standard_id]` | `integer` | The grading standard id to set for the course. If no value is provided for this argument the current grading\_standard will be un-set from this course.This will update the grading\_type for the course to 'letter\_grade' unless it is already 'gpa\_scale'. | | `assignment[omit_from_final_grade]` | `boolean` | Whether this assignment is counted towards a student's final grade. | | `assignment[hide_in_gradebook]` | `boolean` | Whether this assignment is shown in the gradebook. | | `assignment[quiz_lti]` | `boolean` | Whether this assignment should use the Quizzes 2 LTI tool. Sets thesubmission type to 'external\_tool' and configures the external toolattributes to use the Quizzes 2 LTI tool configured for this course.Has no effect if no Quizzes 2 LTI tool is configured. | | `assignment[moderated_grading]` | `boolean` | Whether this assignment is moderated. | | `assignment[grader_count]` | `integer` | The maximum number of provisional graders who may issue grades for thisassignment. Only relevant for moderated assignments. Must be a positivevalue, and must be set to 1 if the course has fewer than two activeinstructors. Otherwise, the maximum value is the number of activeinstructors in the course minus one, or 10 if the course has more than 11active instructors. | | `assignment[final_grader_id]` | `integer` | The user ID of the grader responsible for choosing final grades for thisassignment. Only relevant for moderated assignments. | | `assignment[grader_comments_visible_to_graders]` | `boolean` | Boolean indicating if provisional graders' comments are visible to otherprovisional graders. Only relevant for moderated assignments. | | `assignment[graders_anonymous_to_graders]` | `boolean` | Boolean indicating if provisional graders' identities are hidden fromother provisional graders. Only relevant for moderated assignments. | | `assignment[graders_names_visible_to_final_grader]` | `boolean` | Boolean indicating if provisional grader identities are visible to thethe final grader. Only relevant for moderated assignments. | | `assignment[anonymous_grading]` | `boolean` | Boolean indicating if the assignment is graded anonymously. If true,graders cannot see student identities. | | `assignment[allowed_attempts]` | `integer` | The number of submission attempts allowed for this assignment. Set to -1 for unlimited attempts. | | `assignment[annotatable_attachment_id]` | `integer` | The Attachment ID of the document being annotated.Only applies when submission\_types includes "student\_annotation". | | `assignment[asset_processors][]` | `Array` | Document processors for this assignment. New document processors can only be addedvia the interactive LTI Deep Linking flow (in a browser), not via API token or JWT authentication.Deletion of document processors (passing an empty array) is allowed via API. | | `assignment[peer_review][points_possible]` | `number` | The maximum points possible for peer reviews. | | `assignment[peer_review][grading_type]` | `string` | The strategy used for grading peer reviews.Defaults to "points" if this field is omitted. Allowed values: pass\_fail, percent, letter\_grade, gpa\_scale, points | | `assignment[peer_review][due_at]` | `DateTime` | The day/time the peer reviews are due. Must be between the lock dates if there are lock dates.Accepts times in ISO 8601 format, e.g. 2025-08-20T12:10:00Z. | | `assignment[peer_review][lock_at]` | `DateTime` | The day/time the peer reviews are locked after. Must be after the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2025-08-25T12:10:00Z. | | `assignment[peer_review][unlock_at]` | `DateTime` | The day/time the peer reviews are unlocked. Must be before the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2025-08-15T12:10:00Z. | | `assignment[peer_review][peer_review_overrides][]` | `AssignmentOverride` | List of overrides for the peer reviews. | Returns an [Assignment](#assignment) object. ## [Edit an assignment](#method.assignments_api.update) [AssignmentsApiController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `PUT /api/v1/courses/:course_id/assignments/:id` **Scope:** `url:PUT|/api/v1/courses/:course_id/assignments/:id` Modify an existing assignment. #### Request Parameters: | Parameter | Type | Description | | --------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `assignment[name]` | `string` | The assignment name. | | `assignment[position]` | `integer` | The position of this assignment in the group when displayingassignment lists. | | `assignment[submission_types][]` | `string` | Only applies if the assignment doesn't have student submissions.List of supported submission types for the assignment.Unless the assignment is allowing online submissions, the array shouldonly have one element.If not allowing online submissions, your options are:"online\_quiz""none""on\_paper""discussion\_topic""external\_tool"If you are allowing online submissions, you can have one or manyallowed submission types:"online\_upload""online\_text\_entry""online\_url""media\_recording" (Only valid when the Kaltura plugin is enabled)"student\_annotation" Allowed values: online\_quiz, none, on\_paper, discussion\_topic, external\_tool, online\_upload, online\_text\_entry, online\_url, media\_recording, student\_annotation | | `assignment[allowed_extensions][]` | `string` | Allowed extensions if submission\_types includes "online\_upload"Example:allowed\_extensions: \["docx","ppt"] | | `assignment[turnitin_enabled]` | `boolean` | Only applies when the Turnitin plugin is enabled for a course andthe submission\_types array includes "online\_upload".Toggles Turnitin submissions for the assignment.Will be ignored if Turnitin is not available for the course. | | `assignment[vericite_enabled]` | `boolean` | Only applies when the VeriCite plugin is enabled for a course andthe submission\_types array includes "online\_upload".Toggles VeriCite submissions for the assignment.Will be ignored if VeriCite is not available for the course. | | `assignment[turnitin_settings]` | `string` | Settings to send along to turnitin. See Assignment object definition forformat. | | `assignment[sis_assignment_id]` | `string` | The sis id of the Assignment | | `assignment[integration_data]` | `string` | Data used for SIS integrations. Requires admin-level token with the "Manage SIS" permission. JSON string required. | | `assignment[integration_id]` | `string` | Unique ID from third party integrations | | `assignment[peer_reviews]` | `boolean` | If submission\_types does not include external\_tool,discussion\_topic,online\_quiz, or on\_paper, determines whether or not peer reviewswill be turned on for the assignment. | | `assignment[automatic_peer_reviews]` | `boolean` | Whether peer reviews will be assigned automatically by Canvas or ifteachers must manually assign peer reviews. Does not apply if peer reviewsare not enabled. | | `assignment[notify_of_update]` | `boolean` | If true, Canvas will send a notification to students in the classnotifying them that the content has changed. | | `assignment[group_category_id]` | `integer` | If present, the assignment will become a group assignment assignedto the group. | | `assignment[grade_group_students_individually]` | `integer` | If this is a group assignment, teachers have the options to gradestudents individually. If false, Canvas will apply the assignment'sscore to each member of the group. If true, the teacher can manuallyassign scores to each member of the group. | | `assignment[external_tool_tag_attributes]` | `string` | Hash of external tool parameters if submission\_types is \["external\_tool"].See Assignment object definition for format. | | `assignment[points_possible]` | `number` | The maximum points possible on the assignment. | | `assignment[grading_type]` | `string` | The strategy used for grading the assignment.The assignment defaults to "points" if this field is omitted. Allowed values: pass\_fail, percent, letter\_grade, gpa\_scale, points, not\_graded | | `assignment[due_at]` | `DateTime` | The day/time the assignment is due.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[lock_at]` | `DateTime` | The day/time the assignment is locked after. Must be after the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[unlock_at]` | `DateTime` | The day/time the assignment is unlocked. Must be before the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[description]` | `string` | The assignment's description, supports HTML. | | `assignment[assignment_group_id]` | `integer` | The assignment group id to put the assignment in.Defaults to the top assignment group in the course. | | `assignment[assignment_overrides][]` | `AssignmentOverride` | List of overrides for the assignment.If the +assignment\[assignment\_overrides]+ key is absent, any existingoverrides are kept as is. If the +assignment\[assignment\_overrides]+ key ispresent, existing overrides are updated or deleted (and new ones created,as necessary) to match the provided list. | | `assignment[only_visible_to_overrides]` | `boolean` | Whether this assignment is only visible to overrides(Only useful if 'differentiated assignments' account setting is on) | | `assignment[published]` | `boolean` | Whether this assignment is published.(Only useful if 'draft state' account setting is on)Unpublished assignments are not visible to students. | | `assignment[grading_standard_id]` | `integer` | The grading standard id to set for the course. If no value is provided for this argument the current grading\_standard will be un-set from this course.This will update the grading\_type for the course to 'letter\_grade' unless it is already 'gpa\_scale'. | | `assignment[omit_from_final_grade]` | `boolean` | Whether this assignment is counted towards a student's final grade. | | `assignment[hide_in_gradebook]` | `boolean` | Whether this assignment is shown in the gradebook. | | `assignment[moderated_grading]` | `boolean` | Whether this assignment is moderated. | | `assignment[grader_count]` | `integer` | The maximum number of provisional graders who may issue grades for thisassignment. Only relevant for moderated assignments. Must be a positivevalue, and must be set to 1 if the course has fewer than two activeinstructors. Otherwise, the maximum value is the number of activeinstructors in the course minus one, or 10 if the course has more than 11active instructors. | | `assignment[final_grader_id]` | `integer` | The user ID of the grader responsible for choosing final grades for thisassignment. Only relevant for moderated assignments. | | `assignment[grader_comments_visible_to_graders]` | `boolean` | Boolean indicating if provisional graders' comments are visible to otherprovisional graders. Only relevant for moderated assignments. | | `assignment[graders_anonymous_to_graders]` | `boolean` | Boolean indicating if provisional graders' identities are hidden fromother provisional graders. Only relevant for moderated assignments. | | `assignment[graders_names_visible_to_final_grader]` | `boolean` | Boolean indicating if provisional grader identities are visible to thethe final grader. Only relevant for moderated assignments. | | `assignment[anonymous_grading]` | `boolean` | Boolean indicating if the assignment is graded anonymously. If true,graders cannot see student identities. | | `assignment[allowed_attempts]` | `integer` | The number of submission attempts allowed for this assignment. Set to -1 or null forunlimited attempts. | | `assignment[annotatable_attachment_id]` | `integer` | The Attachment ID of the document being annotated.Only applies when submission\_types includes "student\_annotation". | | `assignment[asset_processors][]` | `Array` | Document processors for this assignment. New document processors can only be addedvia the interactive LTI Deep Linking flow (in a browser), not via API token or JWT authentication.Deletion of document processors (passing an empty array) is allowed via API. | | `assignment[force_updated_at]` | `boolean` | If true, updated\_at will be set even if no changes were made. | | `assignment[peer_review][points_possible]` | `number` | The maximum points possible for peer reviews. | | `assignment[peer_review][grading_type]` | `string` | The strategy used for grading peer reviews.Defaults to "points" if this field is omitted. Allowed values: pass\_fail, percent, letter\_grade, gpa\_scale, points | | `assignment[peer_review][due_at]` | `DateTime` | The day/time the peer reviews are due. Must be between the lock dates if there are lock dates.Accepts times in ISO 8601 format, e.g. 2025-08-20T12:10:00Z. | | `assignment[peer_review][lock_at]` | `DateTime` | The day/time the peer reviews are locked after. Must be after the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2025-08-25T12:10:00Z. | | `assignment[peer_review][unlock_at]` | `DateTime` | The day/time the peer reviews are unlocked. Must be before the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2025-08-15T12:10:00Z. | | `assignment[peer_review][peer_review_overrides][]` | `AssignmentOverride` | List of overrides for the peer reviews.When updating overrides:- Include "id" to update an existing override- Omit "id" to create a new override- Omit an override from the list to delete it | | `assignment[submission_types][]` | `string` | **\[DEPRECATED]** Effective 2021-05-26 (notice given 2021-02-18) Only applies if the assignment doesn't have student submissions. | Returns an [Assignment](#assignment) object. ## [Bulk update assignment dates](#method.assignments_api.bulk_update) [AssignmentsApiController#bulk\_update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `PUT /api/v1/courses/:course_id/assignments/bulk_update` **Scope:** `url:PUT|/api/v1/courses/:course_id/assignments/bulk_update` Update due dates and availability dates for multiple assignments in a course. Accepts a JSON array of objects containing two keys each: +id+, the assignment id, and +all\_dates+, an array of +AssignmentDate+ structures containing the base and/or override dates for the assignment, as returned from the [List assignments](#method.assignments_api.index) endpoint with +include\[]=all\_dates+. This endpoint cannot create or destroy assignment overrides; any existing assignment overrides that are not referenced in the arguments will be left alone. If an override is given, any dates that are not supplied with it will be defaulted. To clear a date, specify null explicitly. All referenced assignments will be validated before any are saved. A list of errors will be returned if any provided dates are invalid, and no changes will be saved. The bulk update is performed in a background job, use the [Progress API](https://developerdocs.instructure.com/services/canvas/resources/pages/3xnEhMZQuJstdXB8KHiv#method.progress.show) to check its status. #### Example Request: ```bash curl 'https:///api/v1/courses/1/assignments/bulk_update' \ -X PUT \ --data '[{ "id": 1, "all_dates": [{ "base": true, "due_at": "2020-08-29T23:59:00-06:00" }, { "id": 2, "due_at": "2020-08-30T23:59:00-06:00" }] }]' \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " ``` Returns a [Progress](/services/canvas/resources/progress#progress) object. ## [List assignment overrides](#method.assignment_overrides.index)
At this point the app should notice that the URL of the webview has changed to contain `code=` somewhere in the query string. The app can then extract the code, and use it along with the client\_id and client\_secret to obtain the final access\_key. #### [Step 3: Exchange the code for the final access token](#oauth2-flow-3) [Back to Top](#top) To get a new access token and refresh token, send a [POST request to login/oauth2/token](/services/canvas/oauth2/file.oauth_endpoints#post-login-oauth2-token) with the following parameters: **Parameters** | Parameter | Value | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | grant\_type | authorization\_code | | client\_id | Your client\_id | | client\_secret | Your client\_secret | | redirect\_uri | If a redirect\_uri was passed to the initial request in step 1, the same redirect\_uri must be given here. | | code | code from canvas | | replace\_tokens | (optional) If this option is set to \`1\`, existing access tokens issued for this developer key/secret will be destroyed and replaced with the new token that is returned from this request | Note that the once the code issued in step 2 is used in a POST request to this endpoint, it is invalidated and further requests for tokens with the same code will fail. ### [Using an Access Token to authenticate requests](#using-access-tokens) [Back to Top](#top) Once you have an OAuth access token, you can use it to make API requests. If possible, using the HTTP Authorization header is recommended. OAuth2 Token sent in header: ```bash curl -H "Authorization: Bearer " "https://canvas.instructure.com/api/v1/courses" ``` Sending the access token in the query string or POST parameters is also supported, but discouraged as it increases the chances of the token being logged or leaked in transit. OAuth2 Token sent in query string: ```bash curl "https://canvas.instructure.com/api/v1/courses?access_token=" ``` ### [Using a Refresh Token to get a new Access Token](#using-refresh-tokens) [Back to Top](#top) Access tokens have a 1 hour lifespan. When the refresh flow is taken, Canvas will update the access token to a new value, reset the expiration timer, and return the new access token as part of the response. When refreshing tokens the user will not be asked to authorize the application again. To refresh the access token, send a [POST request to login/oauth2/token](/services/canvas/oauth2/file.oauth_endpoints#post-login-oauth2-token) with the following parameters: **Parameters** | Parameter | Value | | -------------- | ------------------------------------------------- | | grant\_type | refresh\_token | | client\_id | Your client\_id | | client\_secret | Your client\_secret | | refresh\_token | refresh\_token from initial access\_token request | The response to this request will not contain a new refresh token; the same refresh token is to be reused. ### [Logging Out](/services/canvas/oauth2/file.oauth_endpoints#delete-login-oauth2-token) [Back to Top](#top) To logout, simply send a [DELETE request to login/oauth2/token](/services/canvas/oauth2/file.oauth_endpoints#delete-login-oauth2-token) ## [Accessing LTI Advantage Services](#accessing-lti-advantage-services) [Back to Top](#top) LTI Advantage services, such as [Names and Role Provisioning Services](https://www.imsglobal.org/spec/lti-nrps/v2p0) and [Assignment and Grade Services](https://www.imsglobal.org/spec/lti-ags/v2p0/), require use of a client credentials grant flow for request authentication. This workflow is best summarized on the IMS Security Framework (specifically [Section 4](https://www.imsglobal.org/spec/security/v1p0/#using-oauth-2-0-client-credentials-grant)). Our goal here is to highlight some nuances that might help you access these services in Canvas, rather than describing the specification in detail. ### [Step 1: Developer Key Setup](#developer-key-setup) [Back to Top](#top) Before the client\_credentials grant flow can be achieved, an [LTI developer key must be created](https://community.canvaslms.com/t5/Admin-Guide/How-do-I-configure-an-LTI-key-for-an-account/ta-p/140). During developer key configuration, a public JWK can either be configured statically or can be dynamically rotated by providing JWKs by a URL that Canvas can reach. Tools may also use a previously issued client\_credentials token to [retroactively rotate the public JWK via an API request](/services/canvas/resources/public_jwk). The JWK must include an alg and use. **Example JWK** ``` "public_jwk": { "kty":"RSA", "alg":"RS256", "e":"AQAB", "kid":"8f796179-7ac4-48a3-a202-fc4f3d814fcd", "n":"nZA7QWcIwj-3N_RZ1qJjX6CdibU87y2l02yMay4KunambalP9g0fU9yILwLX9WYJINcXZDUf6QeZ-SSbblET-h8Q4OvfSQ7iuu0WqcvBGy8M0qoZ7I-NiChw8dyybMJHgpiP_AyxpCQnp3bQ6829kb3fopbb4cAkOilwVRBYPhRLboXma0cwcllJHPLvMp1oGa7Ad8osmmJhXhN9qdFFASg_OCQdPnYVzp8gOFeOGwlXfSFEgt5vgeU25E-ycUOREcnP7BnMUk7wpwYqlE537LWGOV5z_1Dqcqc9LmN-z4HmNV7b23QZW4_mzKIOY4IqjmnUGgLU9ycFj5YGDCts7Q", "use":"sig" } ``` ### [Step 2: Request an access token](#request-access-token) [Back to Top](#top) Once the developer key is configured and turned on, your tool can [request an LTI access token using the client\_credentials grant](/services/canvas/oauth2/file.oauth_endpoints#post-login-oauth2-token). This request must be signed by an RSA256 private key with a public key that is configured on the developer key as described in [Step 1: Developer Key Setup](#developer-key-setup). ### [Step 3: Use the access token to access LTI services](#use-access-token) [Back to Top](#top) Once you have an access token, you can use it to make LTI service requests. The access token must be included as a Bearer token in the Authorization header: ```bash curl -H "Authorization: Bearer " "https:///api/lti/courses/:course_id/names_and_roles" ``` Access tokens only work in the context of where a tool has been deployed. Tools can only access line items that are associated with their tool. The following endpoints are currently supported: #### Names and Role Provisioning Services * [Names and Role API](/services/canvas/resources/names_and_role) #### Assignment and Grade Services * [Line Items](/services/canvas/resources/line_items) * [Score](/services/canvas/resources/score) * [Result](/services/canvas/resources/result) *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # OAuth2 Endpoints {% hint style="warning" %} Developer keys issued after Oct 2015 generate tokens with a 1 hour expiration. Applications must use [refresh tokens](/services/canvas/oauth2/file.oauth#using-refresh-tokens) to generate new access tokens. {% endhint %} * [GET login/oauth2/auth](#get-login-oauth2-auth) * [POST login/oauth2/token](#post-login-oauth2-token) * [DELETE login/oauth2/token](#delete-login-oauth2-token) * [GET login/session\_token](#get-login-session-token) ## GET login/oauth2/auth ### GET https\://\/login/oauth2/auth?client\_id=XXX\&response\_type=code\&redirect\_uri=\%20\%20\ #### Parameters | Parameter | Required | Description | | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | client\_id | Required | The client id for your registered application. | | response\_type | Required | The type of OAuth2 response requested. The only currently supported value is `code`. | | redirect\_uri | Required | The URL where the user will be redirected after authorization. The domain of this URL must match the domain of the redirect\_uri stored on the developer key, or it must be a subdomain of that domain. For native applications, currently the only supported value is `urn:ietf:wg:oauth:2.0:oob`, signifying that the credentials will be retrieved out-of-band using an embedded browser or other functionality. | | state | Optional | Your application can pass Canvas an arbitrary piece of state in this parameter, which will be passed back to your application in Step 2. It's strongly encouraged that your application pass a unique identifier in the state parameter, and then verify in Step 2 that the state you receive back from Canvas is the same expected value. Failing to do this opens your application to the possibility of logging the wrong person in, as [described here](http://homakov.blogspot.com/2012/07/saferweb-most-common-oauth2.html). | | scope | Optional | This can be used to specify what information the Canvas API access token will provide access to. Canvas API scopes may be found beneath their corresponding endpoints in the "resources" documentation pages. If the developer key does not require scopes and no scope parameter is specified, the access token will have access to all scopes. If the developer key does require scopes and no scope parameter is specified, Canvas will respond with "invalid\_scope." To successfully pass multiple scope values, the scope parameter is included once, with multiple values separated by spaces. Passing multiple scope parameters, as is common in other areas of Canvas, causes only the last value to be applied to the generated token. | | purpose | Optional | This can be used to help the user identify which instance of an application this token is for. For example, a mobile device application could provide the name of the device. | | force\_login | Optional | Set to '1' if you want to force the user to enter their credentials, even if they're already logged into Canvas. By default, if a user already has an active Canvas web session, they will not be asked to re-enter their credentials. | | unique\_id | Optional | Set to the user's username to be populated in the login form in the event that the user must authenticate. | | prompt | Optional | If set to `none`, Canvas will immediately redirect to the `redirect_uri`. If the caller has a valid session with a "remember me" token or a token from a trusted Developer Key, the redirect will contain a `code=XYZ` param. If the caller has no session, the redirect will contain an `error=login_required` param. If the caller has a session, but no "remember me" or trusted token, the redirect will contain an `error=interaction_required` param. | ## POST login/oauth2/token See [Section 4.1.3](http://tools.ietf.org/html/rfc6749#section-4.1.3) of the OAuth2 RFC for more information about this process. ### POST /login/oauth2/token #### Parameters | Parameter | Required | Description | | ----------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | grant\_type | Required | Values currently supported: "authorization\_code", "refresh\_token", and "client\_credentials". | | client\_id | Required for grant\_types: authorization\_code, refresh\_token | The client id for your registered application. | | client\_secret | Required for grant\_types: authorization\_code, refresh\_token | The client secret for your registered application. | | redirect\_uri | Required for grant\_types: authorization\_code, refresh\_token | If a redirect\_uri was passed to the initial request in step 1, the same redirect\_uri must be given here. | | code | Required for grant\_type: authorization\_code | Required if grant\_type is authorization\_code. The code you received in a redirect response. | | refresh\_token | Required for grant\_type: refresh\_token | Required if grant\_type is refresh\_token. The refresh\_token you received in a redirect response. | | client\_assertion\_type | Required for grant\_type: client\_credentials | Currently the only supported value for this field is \`urn:ietf:params:oauth:client-assertion-type:jwt-bearer\`. | | client\_assertion | Required for grant\_type: client\_credentials | The signed jwt used to request an access token. Includes the value of Developer Key id as the sub claim of the jwt body. Should be signed by the private key of the stored public key on the DeveloperKey. | | scope | Required for grant\_type: client\_credentials | A list of scopes to be granted to the token. Currently only IMS defined scopes may be used. | #### Canvas API example responses For grant\_type of code or refresh\_token: | Parameter | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | access\_token | The OAuth2 Canvas API access token. | | token\_type | The type of token that is returned. | | user | A JSON object of canvas user id and user name. | | refresh\_token | The OAuth2 refresh token. | | expires\_in | Seconds until the access token expires. | | canvas\_region | For hosted Canvas, the AWS region (e.g. us-east-1) in which the institution that provided this token resides. For local or open source Canvas, this will have a value of "unknown". This field is safe to ignore. | When using grant\_type=code (ex: for Canvas API access): ``` { "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "token_type": "Bearer", "user": {"id":42, "name": "Jimi Hendrix"}, "refresh_token": "tIh2YBWGiC0GgGRglT9Ylwv2MnTvy8csfGyfK2PqZmkFYYqYZ0wui4tzI7uBwnN2", "expires_in": 3600, "canvas_region": "us-east-1" } ``` When using grant\_type=refresh\_token, the response will not contain a new refresh token since the same refresh token can be used multiple times: ``` { "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "token_type": "Bearer", "user": {"id":42, "name": "Jimi Hendrix"}, "expires_in": 3600 } ``` If scope=/auth/userinfo was specified in the [GET login/oauth2/auth](#get-login-oauth2-auth) request (ex: when using Canvas as an authentication service) then the response that results from [POST login/oauth2/token](#post-login-oauth2-token) would be: ``` { "access_token": null, "token_type": "Bearer", "user":{"id": 42, "name": "Jimi Hendrix"} } ``` #### Examples using client\_credentials When using grant\_type=client\_credentials (ex: [to access LTI Advantage Services](/services/canvas/oauth2/file.oauth#accessing-lti-advantage-services)): **Example request** This request must be signed by an RSA256 private key with a public key that is configured on the developer key as described in [Step 1: Developer Key Setup](/services/canvas/oauth2/file.oauth#developer-key-setup). ``` { "grant_type": "client_credentials", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "client_assertion": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjIwMTktMDYtMjFUMTQ6NTk6MzBaIn0.eyJpc3MiOiJodHRwczovL3d3dy5teS10b29sLmNvbSIsInN1YiI6Ilx1MDAzY2NsaWVudF9pZFx1MDAzZSIsImF1ZCI6Imh0dHA6Ly9cdTAwM2NjYW52YXNfZG9tYWluXHUwMDNlL2xvZ2luL29hdXRoMi90b2tlbiIsImlhdCI6MTU2MTc1MDAzMSwiZXhwIjoxNTYxNzUwNjMxLCJqdGkiOiJkZmZkYmRjZS1hOWYxLTQyN2ItOGZjYS02MDQxODIxOTg3ODMifQ.lUHCwDqx2ukKQ2vwoz_824IVcyq-rNdJKVpGUiJea5-Ybk_VfyKW5v0ky-4XTJrGHkDcj0T9J8qKfYbikqyetK44yXx1YGo-2Pn2GEZ26bZxCnuDUDhbqN8OZf4T8DnZsYP4OyhOseHERsHCzKF-SD2_Pk6ES5-Z8J55_aMyS3w3tl4nJtwsMm6FbMDp_FhSGE4xTwkBZ2KNM4JqkCwHGX_9KcpsPsHRFQjn9ysTeg-Qf7H2QFgFMFjsfQX-iSL_bQoC2npSz7rQ8awKMhCEYdMYZk2vVhQ7XQ8ysAyf3m1vlLbHjASpztcAB0lz_DJysT0Ep-Rh311Qf_vXHexjVA", "scope": "https://purl.imsglobal.org/spec/lti-ags/lineitem https://purl.imsglobal.org/spec/lti-ags/result/read" } ``` Below is an example of the decoded client\_assertion JWT in the above request: ``` //Header { "typ": "JWT", "alg": "RS256", "kid": "2019-06-21T14:59:30Z" } //Payload { "iss": "https://www.my-tool.com", "sub": "", "aud": "https:///login/oauth2/token", "iat": 1561750031, "exp": 1561750631, "jti": "dffdbdce-a9f1-427b-8fca-604182198783" } ``` NOTE: * the value of the sub claim should match the client\_id of the developer key in Canvas. * the value of the aud claim should contain either the domain of the Canvas account where the desired data resides, or the domain of the LTI 1.3 OIDC Auth endpoint, as described [here](/services/canvas/external-tools/lti/file.lti_launch_overview#step-2). * if the public key defined on the developer key is a JWK set (specified by an URL) the kid (key ID) value in the signed JWT header must match one of the public keys returned by the public key URL. **Example Response** | Parameter | Description | | ------------- | ------------------------------------------------------------------------- | | access\_token | The OAuth2 client\_credentials access token. | | token\_type | The type of token that is returned. | | expires\_in | Seconds until the access token expires. | | scope | The scope or space delimited list of scopes granted for the access token. | ``` { "access_token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ3d3cuZXhhbXBsZS5jb20iLCJpYXQiOiIxNDg1OTA3MjAwIiwiZXhwIjoiMTQ4NTkwNzUwMCIsImltc2dsb2JhbC5vcmcuc2VjdXJpdHkuc2NvcGUiOiJMdGlMaW5rU2V0dGluZ3MgU2NvcmUuaXRlbS5QVVQifQ.UWCuoD05KDYVQHEcciTV88YYtWWMwgb3sTbrjwxGBZA", "token_type" : "Bearer", "expires_in" : 3600, "scope" : "https://purl.imsglobal.org/spec/lti-ags/lineitem https://purl.imsglobal.org/spec/lti-ags/result/read" } ``` ## DELETE login/oauth2/token If your application supports logout functionality, you can revoke your own access token. This is useful for security reasons, as well as removing your application from the list of tokens on the user's profile page. Simply make an authenticated request to the following endpoint by including an Authorization header or providing the access\_token as a request parameter. ### DELETE /login/oauth2/token #### Parameters | Parameter | Required | Description | | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | expire\_sessions | Optional | Set this to '1' if you want to end all of the user's Canvas web sessions. Without this argument, the endpoint will leave web sessions intact.Additionally, if the user logged in to Canvas via a delegated authentication provider, and the provider supports Single Log Out functionality, the response will contain a forward\_url key. If you are still in control of the user's browsing session, it is recommended to then redirect them to this URL, in order to also log them out from where their session originated. Beware that it is unlikely that control will be returned to your application after this redirect. | #### Example responses ``` { "forward_url": "https://idp.school.edu/opaque_url" } ``` ## GET login/session\_token If your application needs to begin a normal web session in order to access features not supported via API (such as quiz taking), you can use your API access token in order to get a time-limited URL that can be fed to a browser or web view to begin a new web session. ### GET /login/session\_token #### Parameters | Parameter | Required | Description | | ---------- | -------- | ---------------------------------------------------------------------------------------------- | | return\_to | Optional | An optional URL to begin the web session at. Otherwise the user will be sent to the dashboard. | #### Example responses ``` { "session_url": "https://canvas.instructure.com/opaque_url" } ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Developer Keys Developer keys are OAuth2 client ID and secret pairs stored in Canvas that allow third-party applications to request access to Canvas API endpoints via the [OAuth2 flow](/services/canvas/oauth2/file.oauth). Access is granted after a user authorizes an app and Canvas creates an API access token that’s returned in the final request of the OAuth2 flow. Developer keys created in a root account, by root account administrators or Instructure employees, are only functional for the account they are created in and its sub-accounts. Developer keys created globally, by an Instructure employee, are functional in any Canvas account where they are enabled. By scoping the tokens, Canvas allows root account administrators to manage the specific API endpoints that tokens issued from a developer key have access to. ## Developer Key Scopes Developer key scopes allow root account administrators to restrict the tokens issued from developer keys to a subset of Canvas API endpoints in their account. Developer keys may be scoped or unscoped. Unscoped keys will have access to all Canvas resources available to the authorizing user. The following applies to scoped developer keys only: ### What are developer key scopes in Canvas? Each Canvas API endpoint has an associated scope. Canvas developer key scopes can only be enabled/disabled by a root account administrator or an Instructure employee. Scopes take the following form: ``` url:| ``` For example, the corresponding scope for the `GET /api/v1/courses/:course_id/rubrics` API endpoint would be ``` url:GET|/api/v1/courses/:course_id/rubrics ``` ### How do developer key scopes function? When requesting an access token, third-party applications should specify a `scope` parameter (see the [oauth endpoints documentation](/services/canvas/oauth2/file.oauth_endpoints#get-login-oauth2-auth)). The requested scopes must be a subset of the scopes set for the developer key. When a client makes any API request, Canvas will verify the requested endpoint's scope has been granted by the account administrator to the developer key of the request's access token. If the requested endpoint's scope has not been granted Canvas will respond with `401 Unauthorized`. ### Who can grant or revoke scopes for a developer key? For developer keys created in a specific root account, administrators for that account may grant or revoke scopes. When requesting a developer key, application owners should communicate with administrators which scopes their integrations require. For global developer keys, an Instructure employee may grant or revoke scopes. *Note:* If a scope is removed from a developer key, all access tokens derived from that key will be invalidated. In this case, clients should request a new access token. ### Where can I see what scopes are available? View the complete list of [token scopes](/services/canvas/resources/api_token_scopes). Scopes may also be found beneath their corresponding endpoints in the "resources" documentation pages. ### Configuring scopes on a developer key When creating or editing an API developer key, administrators can configure scopes in two ways: **Manual** - Browse and select scopes from a grouped list of all available Canvas API endpoints. **Paste Scopes** - Paste a list of scope strings directly into a text field. Scopes should be entered one per line or separated by spaces, using the format described above: ``` url:GET|/api/v1/courses/:course_id/rubrics url:POST|/api/v1/courses/:course_id/assignments ``` Any scope strings that are not recognized as valid Canvas API scopes will be flagged as invalid. The UI will display a warning listing the invalid scopes, and saving will be blocked until they are corrected or removed. ## Developer Key Management Developer key management features allow root account administrators to turn global developer keys "on" and "off" for only their account. ### What management features are available? Root account administrators may enable or disable global developer keys for their specific account. This means that vendors who wish to have integrations that work in any Canvas account may request a global developer key from Instructure allowing account administrators enable the key for their account. ### How do management features function? When a client uses the [OAuth2 Auth endpoint](/services/canvas/oauth2/file.oauth_endpoints#get-login-oauth2-auth) as part of the flow to retrieve an access token canvas will check the developer key associated with the `client_id`. If the developer key is not enabled in the requested account, Canvas will respond with `unauthorized_client`. When a client makes any API request, Canvas will check the developer key associated with the access token used in the request. If the developer key is not enabled for the requested account, Canvas will respond with `401 Unauthorized`. ## Other Considerations ### Maximum number of scopes When clients request an access token they may specify what scopes the token needs (see the [oauth endpoints documentation](/services/canvas/oauth2/file.oauth_endpoints#get-login-oauth2-auth)). Because the client sends the scopes they require in a GET request, the maximum number of scopes one access token can specify is limited by the maximum HTTP header size Canvas allows (8000 chars). On average, an access token may use up to 110 scopes. This number will vary depending on the actual length of the scopes used and any other headers sent in the [login oauth2 request](/services/canvas/oauth2/file.oauth_endpoints#get-login-oauth2-auth) along with the scopes. If the number of scopes required by the client exceeds this limitation, a second access token with the remaining scopes should be requested. ### Canvas API Includes Several Canvas APIs allow specifying an `include` parameter. This parameter allows nesting resources in JSON responses. For example, a request to the [assignment index endpoint](https://developerdocs.instructure.com/services/canvas/oauth2/pages/fmw03fjQMjjL5AFja2sQ#method.assignments_api.index) could be made to include the submission objects for each assignment. Responses to requests made with a scoped access token only support this functionality when the 'Allow Include Parameters' option is also enabled. When this option is disabled, a request is made with a scoped token Canvas will ignore `include` and `includes` parameters. ### Developer Key Scope Changes During the lifetime of a developer key, scopes may be added or removed by account administrators. Below is a description of possible changes and how each will affect access tokens: #### New scopes are added to a developer key Access tokens issued prior to the addition of the new scope will continue to function. These access tokens will not, however, be usable with the new scope. To access the newly added resources clients should request a new access token with scopes. The requested scopes must be a subset of the scopes on the developer key. #### Scopes are removed from a developer key Access tokens issued prior to the removal of the scope(s) will *not* continue to function. Clients should request a new access token with scopes. The requested scopes must be a subset of the scopes on the developer key. #### An unscoped developer key becomes scoped Access tokens issued prior to the change will *not* continue to function. Clients should request a new access token with scopes. The requested scopes must be a subset of the scopes on the developer key. If the client attempts to request a new access token without specifying scopes Canvas will respond with an error. For details on unscoped vs scoped developer key see `Developer Key Scopes` above. #### A scoped developer key becomes unscoped Access tokens issued prior to the change will continue to function *and* have access to all resources of the authorizing user. Clients may continue to request scoped access tokens, but these tokens will be functional for all resources available to the authorizing user. For details on unscoped vs scoped developer key see `Developer Key Scopes` above. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Resources # Access Tokens #### A Token object looks like: ```js { // The internal database ID of the token. "id": null, // The time the token was created. "created_at": null, // The time the token will permanently expire, or null if it does not // permanently expire. "expires_at": null, // The current state of the token. One of 'active', 'pending', 'disabled', or // 'deleted'. "workflow_state": null, // Whether the token should be remembered across sessions. Only applicable for // OAuth tokens. "remember_access": null, // The scopes associated with the token. If empty, there are no scope // limitations. "scopes": null, // If the token was created while masquerading, this is the ID of the real user. // Otherwise, null. "real_user_id": null, // The actual access token. Only included when the token is first created. "token": null, // A short, unique string that can be used to look up the token. "token_hint": null, // The ID of the user the token belongs to. "user_id": null, // The purpose of the token. "purpose": null, // If the token was created by an OAuth application, this is the name of that // application. Otherwise, null. "app_name": null, // Whether the current user can manually regenerate this token. "can_manually_regenerate": null } ``` ## [List access tokens for a user](#method.tokens.user_generated_tokens) [TokensController#user\_generated\_tokens](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `GET /api/v1/users/:user_id/user_generated_tokens` **Scope:** `url:GET|/api/v1/users/:user_id/user_generated_tokens` Returns a list of manually generated access tokens for the specified user. Note that the actual token values are only returned when the token is first created. #### Request Parameters: | Parameter | Type | Description | | ---------- | --------- | ------------------------------------------------------------------------- | | `per_page` | `integer` | The number of results to return per page. Defaults to 10. Maximum of 100. | Returns a list of [Token](#token) objects. ## [Show an access token](#method.tokens.show) [TokensController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `GET /api/v1/users/:user_id/tokens/:id` **Scope:** `url:GET|/api/v1/users/:user_id/tokens/:id` The ID can be the actual database ID of the token, or the 'token\_hint' value. ## [Create an access token](#method.tokens.create) [TokensController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `POST /api/v1/users/:user_id/tokens` **Scope:** `url:POST|/api/v1/users/:user_id/tokens` Create a new access token for the specified user. If the user is not the current user, the token will be created as "pending", and must be activated by the user before it can be used. #### Request Parameters: | Parameter | Type | Description | | ------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `token[purpose]` | Required `string` | The purpose of the token. | | `token[expires_at]` | `DateTime` | The time at which the token will expire. | | `token[scopes][]` | `Array` | The scopes to associate with the token.Ignored if the default developer key does not have the "enable scopes" option enabled.In such cases, the token will inherit the user's permissions instead. | ## [Update an access token](#method.tokens.update) [TokensController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `PUT /api/v1/users/:user_id/tokens/:id` **Scope:** `url:PUT|/api/v1/users/:user_id/tokens/:id` Update an existing access token. The ID can be the actual database ID of the token, or the 'token\_hint' value. Regenerating an expired token requires a new expiration date. #### Request Parameters: | Parameter | Type | Description | | ------------------- | ---------- | ---------------------------------------- | | `token[purpose]` | `string` | The purpose of the token. | | `token[expires_at]` | `DateTime` | The time at which the token will expire. | | `token[scopes][]` | `Array` | The scopes to associate with the token. | | `token[regenerate]` | `boolean` | Regenerate the actual token. | ## [Delete an access token](#method.tokens.destroy) [TokensController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `DELETE /api/v1/users/:user_id/tokens/:id` **Scope:** `url:DELETE|/api/v1/users/:user_id/tokens/:id` The ID can be the actual database ID of the token, or the 'token\_hint' value. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Accessibility Course Scans ## [Trigger accessibility course scan](#method.accessibility_course_scans.create) [AccessibilityCourseScansController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accessibility_course_scans_controller.rb) #### `POST /api/v1/users/:user_id/educator_accessibility_course_scan` **Scope:** `url:POST|/api/v1/users/:user_id/educator_accessibility_course_scan` Queues a background job that scans all a11y-enabled courses where the user has an active teacher or designer enrollment. Idempotent — if a scan is already queued or running, the existing Progress is returned. Requires the educator\_dashboard feature flag on the root account and a11y\_checker\_account\_statistics on site admin. #### Request Parameters: | Parameter | Type | Description | | --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | | `user_id` | Required `string` | The ID of the user, or "self" for the current user.The requesting user may only trigger a scan for themselves. | Returns a [Progress](/services/canvas/resources/progress#progress) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Accessibility Course Statistics #### An AccessibilityCourseStatistic object looks like: ```js // Per-course accessibility issue counts for a user's active teacher/designer // courses. { // The ID of the accessibility course statistic record "id": 1, // The ID of the course "course_id": 42, // The name of the course "course_name": "Introduction to Biology", // The course code (short name) of the course "course_code": "BIO101", // Whether the course is published "published": true, // The number of active accessibility issues in the course "active_issue_count": 5, // The number of resolved accessibility issues in the course "resolved_issue_count": 3, // The number of closed accessibility issues in the course "closed_issue_count": 2, // The workflow state of the statistic record "workflow_state": "active", // The date and time the record was created "created_at": "2026-01-01T00:00:00Z", // The date and time the record was last updated "updated_at": "2026-01-02T00:00:00Z" } ``` ## [List accessibility course statistics](#method.accessibility_course_statistics.index) [AccessibilityCourseStatisticsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accessibility_course_statistics_controller.rb) #### `GET /api/v1/users/:user_id/educator_accessibility_course_statistics` **Scope:** `url:GET|/api/v1/users/:user_id/educator_accessibility_course_statistics` Returns per-course accessibility issue statistics for the current user's active teacher and designer courses. Only courses where the accessibility checker is enabled and whose workflow state is neither completed nor deleted are included. Only statistic records with workflow\_state "active" are returned. Requires the educator\_dashboard feature flag to be enabled on the root account, and a11y\_checker\_account\_statistics on site admin plus a11y\_checker on the account (i.e. a11y\_checker\_account\_statistics? must be true). #### Request Parameters: | Parameter | Type | Description | | -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | Required `string` | The ID of the user, or "self" for the current user.The requesting user may only retrieve their own statistics. | | `enrollment_term_id` | `string` | When present, only include courses that belong to the given enrollmentterm(s). Accepts a single term id or an array(enrollment\_term\_id\[]=1\&enrollment\_term\_id\[]=2), and each value may be aterm id or SIS term id. Returns 404 if any given term does not exist inthis account. | Returns a list of [AccessibilityCourseStatistic](#accessibilitycoursestatistic) objects. ## [List accessibility course statistic terms](#method.accessibility_course_statistics.terms) [AccessibilityCourseStatisticsController#terms](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accessibility_course_statistics_controller.rb) #### `GET /api/v1/users/:user_id/educator_accessibility_course_terms` **Scope:** `url:GET|/api/v1/users/:user_id/educator_accessibility_course_terms` Returns the distinct enrollment terms that the current user's active teacher and designer courses belong to -- the same courses reported by the List accessibility course statistics endpoint. Use this to populate a term filter for that endpoint. There is no "all terms" entry; "all terms" is represented by omitting the enrollment\_term\_id filter. Requires the same account settings and feature flags as the statistics endpoint. #### Request Parameters: | Parameter | Type | Description | | --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- | | `user_id` | Required `string` | The ID of the user, or "self" for the current user.The requesting user may only retrieve their own terms. | Returns a list of [EnrollmentTerm](/services/canvas/resources/enrollment_terms#enrollmentterm) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Account Calendars API for viewing and toggling settings of account calendars. An account calendar is available for each account in Canvas. All account calendars are hidden by default, but administrators with the `manage_account_calendar_visibility` permission may set calendars as visible. Administrators with the `manage_account_calendar_events` permission can create events in visible account calendars, and users associated with an account can add the calendar and see its events (if the calendar is visible). Events on calendars set as `auto_subscribe` calendars will appear on users' calendars even if they do not manually add it. #### An AccountCalendar object looks like: ```js { // the ID of the account associated with this calendar "id": 204, // the name of the account associated with this calendar "name": "Department of Chemistry", // the account's parent ID, or null if this is the root account "parent_account_id": 1, // the ID of the root account, or null if this is the root account "root_account_id": 1, // whether this calendar is visible to users "visible": true, // whether users see this calendar's events without needing to manually add it "auto_subscribe": false, // number of this account's direct sub-accounts "sub_account_count": 0, // Asset string of the account "asset_string": "account_4", // Object type "type": "account", // url to get full detailed events "calendar_event_url": "/accounts/2/calendar_events/%7B%7B%20id%20%7D%7D", // whether the user can create calendar events "can_create_calendar_events": true, // API path to create events for the account "create_calendar_event_url": "/accounts/2/calendar_events", // url to open the more options event editor "new_calendar_event_url": "/accounts/6/calendar_events/new" } ``` ## [List available account calendars](#method.account_calendars_api.index) [AccountCalendarsApiController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `GET /api/v1/account_calendars` **Scope:** `url:GET|/api/v1/account_calendars` Returns a paginated list of account calendars available to the current user. Includes visible account calendars where the user has an account association. #### Request Parameters: | Parameter | Type | Description | | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `search_term` | `string` | When included, searches available account calendars for the term. Returns matchingresults. Term must be at least 2 characters. | #### Example Request: ```bash curl https:///api/v1/account_calendars \ -H 'Authorization: Bearer ' ``` Returns a list of [AccountCalendar](#accountcalendar) objects. ## [Get a single account calendar](#method.account_calendars_api.show) [AccountCalendarsApiController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `GET /api/v1/account_calendars/:account_id` **Scope:** `url:GET|/api/v1/account_calendars/:account_id` Get details about a specific account calendar. #### Example Request: ```bash curl https:///api/v1/account_calendars/204 \ -H 'Authorization: Bearer ' ``` Returns an [AccountCalendar](#accountcalendar) object. ## [Update a calendar](#method.account_calendars_api.update) [AccountCalendarsApiController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `PUT /api/v1/account_calendars/:account_id` **Scope:** `url:PUT|/api/v1/account_calendars/:account_id` Set an account calendar's visibility and auto\_subscribe values. Requires the `manage_account_calendar_visibility` permission on the account. #### Request Parameters: | Parameter | Type | Description | | ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `visible` | `boolean` | Allow administrators with manage\_account\_calendar\_events permissionto create events on this calendar, and allow users to view thiscalendar and its events. | | `auto_subscribe` | `boolean` | When true, users will automatically see events from this account in theircalendar, even if they haven't manually added that calendar. | #### Example Request: ```bash curl https:///api/v1/account_calendars/204 \ -X PUT \ -H 'Authorization: Bearer ' \ -d 'visible=false' \ -d 'auto_subscribe=false' ``` Returns an [AccountCalendar](#accountcalendar) object. ## [Update several calendars](#method.account_calendars_api.bulk_update) [AccountCalendarsApiController#bulk\_update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `PUT /api/v1/accounts/:account_id/account_calendars` **Scope:** `url:PUT|/api/v1/accounts/:account_id/account_calendars` Set visibility and/or auto\_subscribe on many calendars simultaneously. Requires the `manage_account_calendar_visibility` permission on the account. Accepts a JSON array of objects containing 2-3 keys each: `id` (the account's id, required), `visible` (a boolean indicating whether the account calendar is visible), and `auto_subscribe` (a boolean indicating whether users should see these events in their calendar without manually subscribing). Returns the count of updated accounts. #### Example Request: ```bash curl https:///api/v1/accounts/1/account_calendars \ -X PUT \ -H 'Authorization: Bearer ' \ --data '[{"id": 1, "visible": true, "auto_subscribe": false}, {"id": 13, "visible": false, "auto_subscribe": true}]' ``` ## [List all account calendars](#method.account_calendars_api.all_calendars) [AccountCalendarsApiController#all\_calendars](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `GET /api/v1/accounts/:account_id/account_calendars` **Scope:** `url:GET|/api/v1/accounts/:account_id/account_calendars` Returns a paginated list of account calendars for the provided account and its first level of sub-accounts. Includes hidden calendars in the response. Requires the `manage_account_calendar_visibility` permission. #### Request Parameters: | Parameter | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search_term` | `string` | When included, searches all descendent accounts of provided account for theterm. Returns matching results. Term must be at least 2 characters. Can becombined with a filter value. | | `filter` | `string` | When included, only returns calendars that are either visible or hidden. Canbe combined with a search term. Allowed values: visible, hidden | #### Example Request: ```bash curl https:///api/v1/accounts/1/account_calendars \ -H 'Authorization: Bearer ' ``` Returns a list of [AccountCalendar](#accountcalendar) objects. ## [Count of all visible account calendars](#method.account_calendars_api.visible_calendars_count) [AccountCalendarsApiController#visible\_calendars\_count](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `GET /api/v1/accounts/:account_id/visible_calendars_count` **Scope:** `url:GET|/api/v1/accounts/:account_id/visible_calendars_count` Returns the number of visible account calendars. #### Example Request: ```bash curl https:///api/v1/accounts/1/visible_calendars_count \ -H 'Authorization: Bearer ' ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Account Domain Lookups ## [Search account domains](#method.account_domain_lookups.search) #### `GET /api/v1/accounts/search` **Scope:** `url:GET|/api/v1/accounts/search` Returns a list of up to 5 matching account domains Partial match on name / domain are supported #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | -------------- | | `name` | `string` | campus name | | `domain` | `string` | no description | | `latitude` | `number` | no description | | `longitude` | `number` | no description | #### Example Request: ```bash curl https:///api/v1/accounts/search \ -G -H 'Authorization: Bearer ' \ -d 'name=utah' ``` #### Example Response: ```js [ { "name": "University of Utah", "domain": "utah.edu", "distance": null, // distance is always nil, but preserved in the api response for backwards compatibility "authentication_provider": "canvas", // which authentication_provider param to pass to the oauth flow; may be NULL }, ... ] ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Account Notifications API for account notifications. #### An AccountNotification object looks like: ```js { // The subject of the notifications "subject": "Attention Students", // The message to be sent in the notification. "message": "This is a test of the notification system.", // When to send out the notification. "start_at": "2013-08-28T23:59:00-06:00", // When to expire the notification. "end_at": "2013-08-29T23:59:00-06:00", // The icon to display with the message. Defaults to warning. "icon": "information", // (Deprecated) The roles to send the notification to. If roles is not passed // it defaults to all roles "roles": ["StudentEnrollment"], // The roles to send the notification to. If roles is not passed it defaults to // all roles "role_ids": [1], // The author of the notification. Available only to admins using include_all. "author": {"id":1,"name":"John Doe"} } ``` ## [Index of active global notification for the user](#method.account_notifications.user_index) [AccountNotificationsController#user\_index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `GET /api/v1/accounts/:account_id/account_notifications` **Scope:** `url:GET|/api/v1/accounts/:account_id/account_notifications` Returns a list of all global notifications in the account for the current user Any notifications that have been closed by the user will not be returned, unless a include\_past parameter is passed in as true. Admins can request all global notifications for the account by passing in an include\_all parameter. #### Request Parameters: | Parameter | Type | Description | | ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------- | | `include_past` | `boolean` | Include past and dismissed global announcements. | | `include_all` | `boolean` | Include all global announcements, regardless of user's role or availability date. Only available to account admins. | | `show_is_closed` | `boolean` | Include a flag for each notification indicating whether it has been read by the user. | #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/users/self/account_notifications ``` Returns a list of [AccountNotification](#accountnotification) objects. ## [Show a global notification](#method.account_notifications.show) [AccountNotificationsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `GET /api/v1/accounts/:account_id/account_notifications/:id` **Scope:** `url:GET|/api/v1/accounts/:account_id/account_notifications/:id` Returns a global notification for the current user A notification that has been closed by the user will not be returned #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/users/self/account_notifications/4 ``` Returns an [AccountNotification](#accountnotification) object. ## [Create a global notification](#method.account_notifications.create) [AccountNotificationsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `POST /api/v1/accounts/:account_id/account_notifications` **Scope:** `url:POST|/api/v1/accounts/:account_id/account_notifications` Create and return a new global notification for an account. #### Request Parameters: | Parameter | Type | Description | | -------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_notification[subject]` | Required `string` | The subject of the notification. | | `account_notification[message]` | Required `string` | The message body of the notification. | | `account_notification[start_at]` | Required `DateTime` | The start date and time of the notification in ISO8601 format.e.g. 2014-01-01T01:00Z | | `account_notification[end_at]` | Required `DateTime` | The end date and time of the notification in ISO8601 format.e.g. 2014-01-01T01:00Z | | `account_notification[icon]` | `string` | The icon to display with the notification.Note: Defaults to warning. Allowed values: warning, information, question, error, calendar | | `account_notification_roles[]` | `string` | The role(s) to send global notification to. Note: ommitting this field will send to everyoneExample:account\_notification\_roles: \["StudentEnrollment", "TeacherEnrollment"] | #### Example Request: ```bash curl -X POST -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/account_notifications \ -d 'account_notification[subject]=New notification' \ -d 'account_notification[start_at]=2014-01-01T00:00:00Z' \ -d 'account_notification[end_at]=2014-02-01T00:00:00Z' \ -d 'account_notification[message]=This is a global notification' ``` #### Example Response: ```js { "subject": "New notification", "start_at": "2014-01-01T00:00:00Z", "end_at": "2014-02-01T00:00:00Z", "message": "This is a global notification" } ``` ## [Update a global notification](#method.account_notifications.update) [AccountNotificationsController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `PUT /api/v1/accounts/:account_id/account_notifications/:id` **Scope:** `url:PUT|/api/v1/accounts/:account_id/account_notifications/:id` Update global notification for an account. #### Request Parameters: | Parameter | Type | Description | | -------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_notification[subject]` | `string` | The subject of the notification. | | `account_notification[message]` | `string` | The message body of the notification. | | `account_notification[start_at]` | `DateTime` | The start date and time of the notification in ISO8601 format.e.g. 2014-01-01T01:00Z | | `account_notification[end_at]` | `DateTime` | The end date and time of the notification in ISO8601 format.e.g. 2014-01-01T01:00Z | | `account_notification[icon]` | `string` | The icon to display with the notification. Allowed values: `warning`, `information`, `question`, `error`, `calendar` | | `account_notification_roles[]` | `string` | The role(s) to send global notification to. Note: ommitting this field will send to everyoneExample:account\_notification\_roles: \["StudentEnrollment", "TeacherEnrollment"] | #### Example Request: ```bash curl -X PUT -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/account_notifications/1 \ -d 'account_notification[subject]=New notification' \ -d 'account_notification[start_at]=2014-01-01T00:00:00Z' \ -d 'account_notification[end_at]=2014-02-01T00:00:00Z' \ -d 'account_notification[message]=This is a global notification' ``` #### Example Response: ```js { "subject": "New notification", "start_at": "2014-01-01T00:00:00Z", "end_at": "2014-02-01T00:00:00Z", "message": "This is a global notification" } ``` ## [Close notification for user. Destroy notification for admin](#method.account_notifications.user_close_notification) [AccountNotificationsController#user\_close\_notification](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `DELETE /api/v1/accounts/:account_id/account_notifications/:id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/account_notifications/:id` If the current user no longer wants to see this account notification, it can be closed with this call. This affects the current user only. If the current user is an admin and they pass a remove parameter with a value of "true", the account notification will be destroyed. This affects all users. #### Request Parameters: | Parameter | Type | Description | | --------- | --------- | --------------------------------- | | `remove` | `boolean` | Destroy the account notification. | #### Example Request: ```bash curl -X DELETE -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/account_notifications/4 ``` Returns an [AccountNotification](#accountnotification) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Account Reports API for accessing account reports. #### A Report object looks like: ```js { // The unique identifier for the report. "id": 1, // The type of report. "report": "sis_export_csv", // The url to the report download. "file_url": "https://example.com/some/path", // The attachment api object of the report. Only available after the report has // completed. "attachment": null, // The status of the report "status": "complete", // The date and time the report was created. "created_at": "2013-12-01T23:59:00-06:00", // The date and time the report started processing. "started_at": "2013-12-02T00:03:21-06:00", // The date and time the report finished processing. "ended_at": "2013-12-02T00:03:21-06:00", // The time (in seconds) the report has been waiting to run, has been running so // far, or took to run to completion, depending on its current state. "run_time": 33.3, // The report parameters "parameters": {"course_id":2,"start_at":"2012-07-13T10:55:20-06:00","end_at":"2012-07-13T10:55:20-06:00"}, // The progress of the report "progress": 100, // This is the current line count being written to the report. It updates every // 1000 records. "current_line": 12000, // The user that initiated the account report. See the Users API for details. "user": null } ``` #### A ReportParameters object looks like: ```js // The parameters returned will vary for each report. { // The canvas id of the term to get grades from "enrollment_term_id": 2, // If true, deleted objects will be included. If false, deleted objects will be // omitted. "include_deleted": false, // The id of the course to report on "course_id": 2, // The sort order for the csv, Options: 'users', 'courses', 'outcomes'. "order": "users", // If true, user data will be included. If false, user data will be omitted. "users": false, // If true, account data will be included. If false, account data will be // omitted. "accounts": false, // If true, term data will be included. If false, term data will be omitted. "terms": false, // If true, course data will be included. If false, course data will be omitted. "courses": false, // If true, section data will be included. If false, section data will be // omitted. "sections": false, // If true, enrollment data will be included. If false, enrollment data will be // omitted. "enrollments": false, // If true, group data will be included. If false, group data will be omitted. "groups": false, // If true, data for crosslisted courses will be included. If false, data for // crosslisted courses will be omitted. "xlist": false, "sis_terms_csv": 1, "sis_accounts_csv": 1, // If true, enrollment state will be included. If false, enrollment state will // be omitted. Defaults to false. "include_enrollment_state": false, // Include enrollment state. Defaults to 'all' Options: ['active'| 'invited'| // 'creation_pending'| 'deleted'| 'rejected'| 'completed'| 'inactive'| 'all'] "enrollment_state": ["all"], // The beginning date for submissions. Max time range is 2 weeks. "start_at": "2012-07-13T10:55:20-06:00", // The end date for submissions. Max time range is 2 weeks. "end_at": "2012-07-13T10:55:20-06:00" } ``` ## [List Available Reports](#method.account_reports.available_reports) [AccountReportsController#available\_reports](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `GET /api/v1/accounts/:account_id/reports` **Scope:** `url:GET|/api/v1/accounts/:account_id/reports` Returns a paginated list of reports for the current context. #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Array of additional information to include."description\_html":: an HTML description of the report, with example output"parameters\_html":: an HTML form for the report parameters Allowed values: description\_html, params\_html | #### API response field: * name The name of the report. * parameters The parameters will vary for each report * last\_run \[Report] The last run of the report. This will be null if the report has never been run. #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts//reports/ ``` #### Example Response: ```js [ { "report":"student_assignment_outcome_map_csv", "title":"Student Competency", "parameters":null, "last_run": { "id": 1, "report": "student_assignment_outcome_map_csv", "file_url": "https://example.com/some/path", "status": "complete", "created_at": "2013-12-01T23:59:00-06:00", "started_at": "2013-12-02T00:03:21-06:00", "ended_at": "2013-12-02T00:03:21-06:00" }, { "report":"grade_export_csv", "title":"Grade Export", "parameters":{ "term":{ "description":"The canvas id of the term to get grades from", "required":true } }, "last_run": null } ] ``` ## [Start a Report](#method.account_reports.create) [AccountReportsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `POST /api/v1/accounts/:account_id/reports/:report` **Scope:** `url:POST|/api/v1/accounts/:account_id/reports/:report` Generates a report instance for the account. Note that "report" in the request must match one of the available report names. To fetch a list of available report names and parameters for each report (including whether or not those parameters are required), see [List Available Reports](#method.account_reports.available_reports). #### Request Parameters: | Parameter | Type | Description | | -------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `parameters[]` | `Hash` | The parameters will vary for each report. To fetch a listof available parameters for each report, see List Available Reports.A few example parameters have been provided below. Note that the exampleparameters provided below may not be valid for every report. | | `parameters[skip_message]` | `boolean` | If true, no message will be sentto the user upon completion of the report. | | `parameters[course_id]` | `integer` | The id of the course to report on.Note: this parameter has been listed to serve as an example and may not bevalid for every report. | | `parameters[users]` | `boolean` | If true, user data will be included. Iffalse, user data will be omitted. Note: this parameter has been listed toserve as an example and may not be valid for every report. | #### Example Request: ```bash curl -X POST \ https:///api/v1/accounts/1/reports/provisioning_csv \ -H 'Authorization: Bearer ' \ -H 'Content-Type: multipart/form-data' \ -F 'parameters[users]=true' \ -F 'parameters[courses]=true' \ -F 'parameters[enrollments]=true' ``` Returns a [Report](/services/canvas/resources/course_reports#report) object. ## [Index of Reports](#method.account_reports.index) [AccountReportsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `GET /api/v1/accounts/:account_id/reports/:report` **Scope:** `url:GET|/api/v1/accounts/:account_id/reports/:report` Shows all reports that have been run for the account of a specific type. #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts//reports/ ``` Returns a list of [Report](/services/canvas/resources/course_reports#report) objects. ## [Status of a Report](#method.account_reports.show) [AccountReportsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `GET /api/v1/accounts/:account_id/reports/:report/:id` **Scope:** `url:GET|/api/v1/accounts/:account_id/reports/:report/:id` Returns the status of a report. #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts//reports// ``` Returns a [Report](/services/canvas/resources/course_reports#report) object. ## [Delete a Report](#method.account_reports.destroy) [AccountReportsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `DELETE /api/v1/accounts/:account_id/reports/:report/:id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/reports/:report/:id` Deletes a generated report instance. #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ -X DELETE \ https:///api/v1/accounts//reports// ``` Returns a [Report](/services/canvas/resources/course_reports#report) object. ## [Abort a Report](#method.account_reports.abort) [AccountReportsController#abort](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `PUT /api/v1/accounts/:account_id/reports/:report/:id/abort` **Scope:** `url:PUT|/api/v1/accounts/:account_id/reports/:report/:id/abort` Abort a report in progress #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ -X PUT \ https:///api/v1/accounts//reports///abort ``` Returns a [Report](/services/canvas/resources/course_reports#report) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Accounts API for accessing account data. #### An Account object looks like: ```js { // the ID of the Account object "id": 2, // The display name of the account "name": "Canvas Account", // The UUID of the account "uuid": "WvAHhY5FINzq5IyRIJybGeiXyFkG3SqHUPb7jZY5", // The account's parent ID, or null if this is the root account "parent_account_id": 1, // The ID of the root account, or null if this is the root account "root_account_id": 1, // The storage quota for the account in megabytes, if not otherwise specified "default_storage_quota_mb": 500, // The storage quota for a user in the account in megabytes, if not otherwise // specified "default_user_storage_quota_mb": 50, // The storage quota for a group in the account in megabytes, if not otherwise // specified "default_group_storage_quota_mb": 50, // The default time zone of the account. Allowed time zones are // {http://www.iana.org/time-zones IANA time zones} or friendlier // {http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html Ruby on Rails // time zones}. "default_time_zone": "America/Denver", // The friendly Ruby on Rails name of the account's default time zone. Since // several Rails time zones can share a single IANA identifier (the value // returned in default_time_zone), this field disambiguates which one is // configured. "default_time_zone_friendly_name": "Mountain Time (US & Canada)", // The account's identifier in the Student Information System. Only included if // the user has permission to view SIS information. "sis_account_id": "123xyz", // The account's identifier in the Student Information System. Only included if // the user has permission to view SIS information. "integration_id": "123xyz", // The id of the SIS import if created through SIS. Only included if the user // has permission to manage SIS information. "sis_import_id": 12, // The number of courses directly under the account (available via include) "course_count": 10, // The number of sub-accounts directly under the account (available via include) "sub_account_count": 10, // The account's identifier that is sent as context_id in LTI launches. "lti_guid": "123xyz", // The state of the account. Can be 'active' or 'deleted'. "workflow_state": "active" } ``` #### A TermsOfService object looks like: ```js { // Terms Of Service id "id": 1, // The given type for the Terms of Service "terms_type": "default", // Boolean dictating if the user must accept Terms of Service "passive": false, // The id of the root account that owns the Terms of Service "account_id": 1, // Content of the Terms of Service "content": "To be or not to be that is the question", // The type of self registration allowed "self_registration_type": "["none", "observer", "all"]" } ``` #### A HelpLink object looks like: ```js { // The ID of the help link "id": "instructor_question", // The name of the help link "text": "Ask Your Instructor a Question", // The description of the help link "subtext": "Questions are submitted to your instructor", // The URL of the help link "url": "#teacher_feedback", // The type of the help link "type": "default", // The roles that have access to this help link "available_to": ["user", "student", "teacher", "admin", "observer", "unenrolled"] } ``` #### A HelpLinks object looks like: ```js { // Help link button title "help_link_name": "Help And Policies", // Help link button icon "help_link_icon": "help", // Help links defined by the account. Could include default help links. "custom_help_links": [{"id":"link1","text":"Custom Link!","subtext":"Something something.","url":"https:\/\/google.com","type":"custom","available_to":["user","student","teacher","admin","observer","unenrolled"],"is_featured":true,"is_new":false,"feature_headline":"Check this out!"}], // Default help links provided when account has not set help links of their own. "default_help_links": [{"available_to":["student"],"text":"Ask Your Instructor a Question","subtext":"Questions are submitted to your instructor","url":"#teacher_feedback","type":"default","id":"instructor_question","is_featured":false,"is_new":true,"feature_headline":""}, {"available_to":["user","student","teacher","admin","observer","unenrolled"],"text":"Search the Canvas Guides","subtext":"Find answers to common questions","url":"https:\/\/community.canvaslms.com\/t5\/Guides\/ct-p\/guides","type":"default","id":"search_the_canvas_guides","is_featured":false,"is_new":false,"feature_headline":""}, {"available_to":["user","student","teacher","admin","observer","unenrolled"],"text":"Report a Problem","subtext":"If Canvas misbehaves, tell us about it","url":"#create_ticket","type":"default","id":"report_a_problem","is_featured":false,"is_new":false,"feature_headline":""}] } ``` ## [List accounts](#method.accounts.index) [AccountsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts` **Scope:** `url:GET|/api/v1/accounts` A paginated list of accounts that the current user can view or manage. Typically, students and even teachers will get an empty list in response, only account admins can view the accounts that they are in. #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Array of additional information to include."lti\_guid":: the 'tool\_consumer\_instance\_guid' that will be sent for this account on LTI launches"registration\_settings":: returns info about the privacy policy and terms of use"services":: returns services and whether they are enabled (requires account management permissions)"course\_count":: returns the number of courses directly under each account"sub\_account\_count":: returns the number of sub-accounts directly under each account Allowed values: lti\_guid, registration\_settings, services, course\_count, sub\_account\_count | Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [List horizon accounts](#method.accounts.horizon_accounts) [AccountsController#horizon\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/horizon_accounts` **Scope:** `url:GET|/api/v1/horizon_accounts` A paginated list of horizon accounts that the current user can view or manage. Returns all accounts with the horizon\_account setting enabled. If there are any horizon accounts and the user has access to Site Admin, Site Admin will also be included in the results. Typically, students and even teachers will get an empty list in response, only account admins can view the accounts that they are in. #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Array of additional information to include."lti\_guid":: the 'tool\_consumer\_instance\_guid' that will be sent for this account on LTI launches"registration\_settings":: returns info about the privacy policy and terms of use"services":: returns services and whether they are enabled (requires account management permissions)"course\_count":: returns the number of courses directly under each account"sub\_account\_count":: returns the number of sub-accounts directly under each account"site\_admin":: returns true if the account is the Site Admin account (only included if true) Allowed values: lti\_guid, registration\_settings, services, course\_count, sub\_account\_count, site\_admin | Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [Get accounts that admins can manage](#method.accounts.manageable_accounts) [AccountsController#manageable\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/manageable_accounts` **Scope:** `url:GET|/api/v1/manageable_accounts` A paginated list of accounts where the current user has permission to create or manage courses. List will be empty for students and teachers as only admins can view which accounts they are in. Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [Get accounts that users can create courses in](#method.accounts.course_creation_accounts) [AccountsController#course\_creation\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/course_creation_accounts` **Scope:** `url:GET|/api/v1/course_creation_accounts` A paginated list of accounts where the current user has permission to create courses. Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [List accounts for course admins](#method.accounts.course_accounts) [AccountsController#course\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/course_accounts` **Scope:** `url:GET|/api/v1/course_accounts` A paginated list of accounts that the current user can view through their admin course enrollments. (Teacher, TA, or designer enrollments). Only returns "id", "name", "workflow\_state", "root\_account\_id" and "parent\_account\_id" Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [Get a single account](#method.accounts.show) [AccountsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:id` **Scope:** `url:GET|/api/v1/accounts/:id` Retrieve information on an individual account, given by id or sis sis\_account\_id. Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. ## [Settings](#method.accounts.show_settings) [AccountsController#show\_settings](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/settings` **Scope:** `url:GET|/api/v1/accounts/:account_id/settings` Returns a JSON object containing a subset of settings for the specified account. It's possible an empty set will be returned if no settings are applicable. The caller must be an Account admin with the manage\_account\_settings permission. #### Example Request: ```bash curl https:///api/v1/accounts//settings \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js {"microsoft_sync_enabled": true, "microsoft_sync_login_attribute_suffix": false} ``` ## [List environment settings](#method.accounts.environment) [AccountsController#environment](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/settings/environment` **Scope:** `url:GET|/api/v1/settings/environment` Return a hash of global settings for the root account This is the same information supplied to the web interface as +ENV.SETTINGS+. #### Example Request: ```bash curl 'http:///api/v1/settings/environment' \ -H "Authorization: Bearer " ``` #### Example Response: ```js { "calendar_contexts_limit": 10, "open_registration": false, ...} ``` ## [Permissions](#method.accounts.permissions) [AccountsController#permissions](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/permissions` **Scope:** `url:GET|/api/v1/accounts/:account_id/permissions` Returns permission information for the calling user and the given account. You may use `self` as the account id to check permissions against the domain root account. The caller must have an account role or admin (teacher/TA/designer) enrollment in a course in the account. See also the [Course](https://developerdocs.instructure.com/services/canvas/resources/pages/Dq3HF46TIgKustPuq4C9#method.courses.permissions) and [Group](https://developerdocs.instructure.com/services/canvas/resources/pages/2YyNPW0XHYoLadMGQAZY#method.groups.permissions) counterparts. #### Request Parameters: | Parameter | Type | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `permissions[]` | `string` | List of permissions to check against the authenticated user.Permission names are documented in the List assignable permissions endpoint. | #### Example Request: ```bash curl https:///api/v1/accounts/self/permissions \ -H 'Authorization: Bearer ' \ -d 'permissions[]=manage_account_memberships' \ -d 'permissions[]=become_user' ``` #### Example Response: ```js {'manage_account_memberships': 'false', 'become_user': 'true'} ``` ## [Get the sub-accounts of an account](#method.accounts.sub_accounts) [AccountsController#sub\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/sub_accounts` **Scope:** `url:GET|/api/v1/accounts/:account_id/sub_accounts` List accounts that are sub-accounts of the given account. #### Request Parameters: | Parameter | Type | Description | | ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `recursive` | `boolean` | If true, the entire account tree underneaththis account will be returned (though still paginated). If false, onlydirect sub-accounts of this account will be returned. Defaults to false. | | `order` | `string` | Sorts the accounts by id or name.Only applies when recursive is false. Defaults to id. Allowed values: id, name | | `include[]` | `string` | Array of additional information to include."course\_count":: returns the number of courses directly under each account"sub\_account\_count":: returns the number of sub-accounts directly under each account Allowed values: course\_count, sub\_account\_count | #### Example Request: ```bash curl https:///api/v1/accounts//sub_accounts \ -H 'Authorization: Bearer ' ``` Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [Get the Terms of Service](#method.accounts.terms_of_service) [AccountsController#terms\_of\_service](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/terms_of_service` **Scope:** `url:GET|/api/v1/accounts/:account_id/terms_of_service` Returns the terms of service for that account Returns a [TermsOfService](#termsofservice) object. ## [Get help links](#method.accounts.help_links) [AccountsController#help\_links](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/help_links` **Scope:** `url:GET|/api/v1/accounts/:account_id/help_links` Returns the help links for that account Returns a [HelpLinks](#helplinks) object. ## [Get the manually-created courses sub-account for the domain root account](#method.accounts.manually_created_courses_account) [AccountsController#manually\_created\_courses\_account](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/manually_created_courses_account` **Scope:** `url:GET|/api/v1/manually_created_courses_account` Returns the sub-account that contains manually created courses for the domain root account. Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. ## [List active courses in an account](#method.accounts.courses_api) [AccountsController#courses\_api](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/courses` **Scope:** `url:GET|/api/v1/accounts/:account_id/courses` Retrieve a paginated list of courses in this account. #### Request Parameters: | Parameter | Type | Description | | ----------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `with_enrollments` | `boolean` | If true, include only courses with at least one enrollment. If false,include only courses with no enrollments. If not present, do not filteron course enrollment status. | | `enrollment_type[]` | `string` | If set, only return courses that have at least one user enrolled inin the course with one of the specified enrollment types. Allowed values: teacher, student, ta, observer, designer | | `enrollment_workflow_state[]` | `string` | If set, only return courses that have at least one user enrolled inin the course with one of the specified enrollment workflow states. Allowed values: active, completed, deleted, invited, pending, creation\_pending, rejected, inactive | | `published` | `boolean` | If true, include only published courses. If false, exclude publishedcourses. If not present, do not filter on published status. | | `completed` | `boolean` | If true, include only completed courses (these may be in state'completed', or their enrollment term may have ended). If false, excludecompleted courses. If not present, do not filter on completed status. | | `blueprint` | `boolean` | If true, include only blueprint courses. If false, exclude them.If not present, do not filter on this basis. | | `blueprint_associated` | `boolean` | If true, include only courses that inherit content from a blueprint course.If false, exclude them. If not present, do not filter on this basis. | | `public` | `boolean` | If true, include only public courses. If false, exclude them.If not present, do not filter on this basis. | | `by_teachers[]` | `integer` | List of User IDs of teachers; if supplied, include only courses taught byone of the referenced users. | | `by_subaccounts[]` | `integer` | List of Account IDs; if supplied, include only courses associated with oneof the referenced subaccounts. | | `hide_enrollmentless_courses` | `boolean` | If present, only return courses that have at least one enrollment.Equivalent to 'with\_enrollments=true'; retained for compatibility. | | `state[]` | `string` | If set, only return courses that are in the given state(s). By default,all states but "deleted" are returned. Allowed values: created, claimed, available, completed, deleted, all | | `enrollment_term_id[]` | `integer` | If set, only includes courses from the specified terms. Can be either a single ID oran array of enrollment term IDs. | | `search_term` | `string` | The partial course name, code, or full ID to match and return in the results list. Must be at least 3 characters. | | `include[]` | `string` | - All explanations can be seen in the Course API index documentation- "sections", "needs\_grading\_count" and "total\_scores" are not valid options at the account level Allowed values: syllabus\_body, term, course\_progress, storage\_quota\_used\_mb, total\_students, teachers, account\_name, concluded, post\_manually | | `sort` | `string` | The column to sort results by. Allowed values: `course_status`, `course_name`, `sis_course_id`, `teacher`, `account_name` | | `order` | `string` | The order to sort the given column by. Allowed values: `asc`, `desc` | | `search_by` | `string` | The filter to search by. "course" searches for course names, course codes,and SIS IDs. "teacher" searches for teacher names Allowed values: course, teacher | | `starts_before` | `Date` | If set, only return courses that start before the value (inclusive)or their enrollment term starts before the value (inclusive)or both the course's start\_at and the enrollment term's start\_at are set to null.The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. | | `ends_after` | `Date` | If set, only return courses that end after the value (inclusive)or their enrollment term ends after the value (inclusive)or both the course's end\_at and the enrollment term's end\_at are set to null.The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. | | `homeroom` | `boolean` | If set, only return homeroom courses. | Returns a list of [Course](/services/canvas/resources/courses#course) objects. ## [Update an account](#method.accounts.update) [AccountsController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `PUT /api/v1/accounts/:id` **Scope:** `url:PUT|/api/v1/accounts/:id` Update an existing account. #### Request Parameters: | Parameter | Type | Description | | ------------------------------------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account[name]` | `string` | Updates the account name | | `account[sis_account_id]` | `string` | Updates the account sis\_account\_idMust have manage\_sis permission and must not be a root\_account. | | `account[default_time_zone]` | `string` | The default time zone of the account. Allowed time zones areIANA time zones or friendlierRuby on Rails time zones. | | `account[default_storage_quota_mb]` | `integer` | The default course storage quota to be used, if not otherwise specified. | | `account[default_user_storage_quota_mb]` | `integer` | The default user storage quota to be used, if not otherwise specified. | | `account[default_group_storage_quota_mb]` | `integer` | The default group storage quota to be used, if not otherwise specified. | | `account[course_template_id]` | `integer` | The ID of a course to be used as a template for all newly created courses.Empty means to inherit the setting from parent account, 0 means to notuse a template even if a parent account has one set. The course must bemarked as a template. | | `account[parent_account_id]` | `integer` | The ID of a parent account to move the account to. The new parent accountmust be in the same root account as the original. The hierarchy ofsub-accounts will be preserved in the new parent account. The caller mustbe an administrator in both the original parent account and the new parentaccount. | | `account[settings][restrict_student_past_view][value]` | `boolean` | Restrict students from viewing courses after end date | | `account[settings][restrict_student_past_view][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][restrict_student_future_view][value]` | `boolean` | Restrict students from viewing courses before start date | | `account[settings][microsoft_sync_enabled]` | `boolean` | Determines whether this account has Microsoft Teams Sync enabled or not.Note that if you are altering Microsoft Teams sync settings you must enablethe Microsoft Group enrollment syncing feature flag. In addition, if you are enablingMicrosoft Teams sync, you must also specify a tenant, login attribute, and a remote attribute.Specifying a suffix to use is optional. | | `account[settings][microsoft_sync_tenant]` | `string` | The tenant this account should use when using Microsoft Teams Sync.This should be an Azure Active Directory domain name. | | `account[settings][microsoft_sync_login_attribute]` | `string` | The attribute this account should use to lookup users when using Microsoft Teams Sync.Must be one of "sub", "email", "oid", "preferred\_username", or "integration\_id". | | `account[settings][microsoft_sync_login_attribute_suffix]` | `string` | A suffix that will be appended to the result of the login attribute when associatingCanvas users with Microsoft users. Must be under 255 characters and contain no whitespace.This field is optional. | | `account[settings][microsoft_sync_remote_attribute]` | `string` | The Active Directory attribute to use when associating Canvas users with Microsoft users.Must be one of "mail", "mailNickname", or "userPrincipalName". | | `account[settings][restrict_student_future_view][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][lock_all_announcements][value]` | `boolean` | Disable comments on announcements | | `account[settings][lock_all_announcements][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][usage_rights_required][value]` | `boolean` | Copyright and license information must be provided for files before they are published. | | `account[settings][usage_rights_required][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][restrict_student_future_listing][value]` | `boolean` | Restrict students from viewing future enrollments in course list | | `account[settings][restrict_student_future_listing][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][conditional_release][value]` | `boolean` | Enable or disable individual learning paths for students based on assessment | | `account[settings][conditional_release][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][enable_course_paces][value]` | `boolean` | Enable or disable course pacing | | `account[settings][enable_course_paces][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][suppress_notifications]` | `boolean` | Suppress notification messages from being created and sent. When set to+true+, all notifications are suppressed. When set to an array ofnotification category slugs (e.g. +\["grading", "announcement"]+), onlynotifications in those categories are suppressed. Set to +false+ toallow all notifications. Root account setting only. | | `account[settings][password_policy]` | `Hash` | Hash of optional password policy configuration parameters for a root account+allow\_login\_suspension+ boolean:: Allow suspension of user logins upon reaching maximum\_login\_attempts+require\_number\_characters+ boolean:: Require the use of number characters when setting up a new password+require\_symbol\_characters+ boolean:: Require the use of symbol characters when setting up a new password+minimum\_character\_length+ integer:: Minimum number of characters required for a new password+maximum\_login\_attempts+ integer:: Maximum number of login attempts before a user is locked outRequired feature option:Enhance password options | | `account[settings][enable_as_k5_account][value]` | `boolean` | Enable or disable Canvas for Elementary for this account | | `account[settings][use_classic_font_in_k5][value]` | `boolean` | Whether or not the classic font is used on the dashboard. Only applies if enable\_as\_k5\_account is true. | | `account[settings][horizon_account][value]` | `boolean` | Enable or disable Canvas Career for this account | | `override_sis_stickiness` | `boolean` | Default is true. If false, any fields containing “sticky” changes will not be updated.See SIS CSV Format documentation for information on which fields can have SIS stickiness | | `account[settings][lock_outcome_proficiency][value]` | `boolean` | \[DEPRECATED] Restrict instructors from changing mastery scale | | `account[lock_outcome_proficiency][locked]` | `boolean` | \[DEPRECATED] Lock this setting for sub-accounts and courses | | `account[settings][lock_proficiency_calculation][value]` | `boolean` | \[DEPRECATED] Restrict instructors from changing proficiency calculation method | | `account[lock_proficiency_calculation][locked]` | `boolean` | \[DEPRECATED] Lock this setting for sub-accounts and courses | | `account[services]` | `Hash` | Give this a set of keys and boolean values to enable or disable services matching the keys | #### Example Request: ```bash curl https:///api/v1/accounts/ \ -X PUT \ -H 'Authorization: Bearer ' \ -d 'account[name]=New account name' \ -d 'account[default_time_zone]=Mountain Time (US & Canada)' \ -d 'account[default_storage_quota_mb]=450' ``` Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. ## [Delete a user from the root account](#method.accounts.remove_user) [AccountsController#remove\_user](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `DELETE /api/v1/accounts/:account_id/users/:user_id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/users/:user_id` Delete a user record from a Canvas root account. If a user is associated with multiple root accounts (in a multi-tenant instance of Canvas), this action will NOT remove them from the other accounts. WARNING: This API will allow a user to remove themselves from the account. If they do this, they won't be able to make API calls or log into Canvas at that account. #### Example Request: ```bash curl https:///api/v1/accounts/3/users/5 \ -H 'Authorization: Bearer ' \ -X DELETE ``` Returns an [User](/services/canvas/resources/users#user) object. ## [Delete multiple users from the root account](#method.accounts.remove_users) [AccountsController#remove\_users](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `DELETE /api/v1/accounts/:account_id/users` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/users` Delete multiple users from a Canvas root account. If a user is associated with multiple root accounts (in a multi-tenant instance of Canvas), this action will NOT remove them from the other accounts. WARNING: This API will allow a user to remove themselves from the account. If they do this, they won't be able to make API calls or log into Canvas at that account. #### Example Request: ```bash curl https:///api/v1/accounts/3/users \ -H 'Authorization: Bearer ' \ -X DELETE -d 'user_ids[]=1' \ -d 'user_ids[]=2' ``` Returns a [Progress](/services/canvas/resources/progress#progress) object. ## [Update multiple users](#method.accounts.update_users) [AccountsController#update\_users](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `PUT /api/v1/accounts/:account_id/users/bulk_update` **Scope:** `url:PUT|/api/v1/accounts/:account_id/users/bulk_update` Updates multiple users in bulk. #### Request Parameters: | Parameter | Type | Description | | ---------- | -------- | ------------------------------------------------------------ | | `user_ids` | `string` | \[Array\]The IDs of the users to update. | | `user` | `Hash` | The attributes to update for each user. | #### Example Request: ```bash curl https:///api/v1/accounts/3/users/bulk_update \ -X PUT \ -H 'Authorization: Bearer ' \ -d 'user_ids[]=1' \ -d 'user_ids[]=2' \ -d 'user[event]=suspend' ``` Returns a [Progress](/services/canvas/resources/progress#progress) object. ## [Restore a deleted user from a root account](#method.accounts.restore_user) [AccountsController#restore\_user](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `PUT /api/v1/accounts/:account_id/users/:user_id/restore` **Scope:** `url:PUT|/api/v1/accounts/:account_id/users/:user_id/restore` Restore a user record along with the most recently deleted pseudonym from a Canvas root account. #### Example Request: ```bash curl https:///api/v1/accounts/3/users/5/restore \ -H 'Authorization: Bearer ' \ -X PUT ``` Returns an [User](/services/canvas/resources/users#user) object. ## [Create a new sub-account](#method.sub_accounts.create) [SubAccountsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/sub_accounts_controller.rb) #### `POST /api/v1/accounts/:account_id/sub_accounts` **Scope:** `url:POST|/api/v1/accounts/:account_id/sub_accounts` Add a new sub-account to a given account. #### Request Parameters: | Parameter | Type | Description | | ----------------------------------------- | ----------------- | ------------------------------------------------------------------------ | | `account[name]` | Required `string` | The name of the new sub-account. | | `account[sis_account_id]` | `string` | The account's identifier in the Student Information System. | | `account[default_storage_quota_mb]` | `integer` | The default course storage quota to be used, if not otherwise specified. | | `account[default_user_storage_quota_mb]` | `integer` | The default user storage quota to be used, if not otherwise specified. | | `account[default_group_storage_quota_mb]` | `integer` | The default group storage quota to be used, if not otherwise specified. | Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. ## [Delete a sub-account](#method.sub_accounts.destroy) [SubAccountsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/sub_accounts_controller.rb) #### `DELETE /api/v1/accounts/:account_id/sub_accounts/:id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/sub_accounts/:id` Cannot delete an account with active courses or active sub\_accounts. Cannot delete a root\_account Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Accounts (LTI) API for accessing account data using an LTI dev key. Allows a tool to get account information via LTI Advantage authorization scheme, which does not require a user session like normal developer keys do. Requires the account lookup scope on the LTI key. #### An Account object looks like: ```js { // the ID of the Account object "id": 2, // The display name of the account "name": "Canvas Account", // The UUID of the account "uuid": "WvAHhY5FINzq5IyRIJybGeiXyFkG3SqHUPb7jZY5", // The account's parent ID, or null if this is the root account "parent_account_id": 1, // The ID of the root account, or null if this is the root account "root_account_id": 1, // The state of the account. Can be 'active' or 'deleted'. "workflow_state": "active" } ``` ## [Get account](#method.lti/account_lookup.show) [Lti::AccountLookupController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/account_lookup_controller.rb) #### `GET /api/lti/accounts/:account_id` **Scope:** `url:GET|/api/lti/accounts/:account_id` Retrieve information on an individual account, given by local or global ID. Returns an [Account](#account) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Admins Manage account role assignments #### An Admin object looks like: ```js { // The unique identifier for the account role/user assignment. "id": 1023, // The account role assigned. This can be 'AccountAdmin' or a user-defined role // created by the Roles API. "role": "AccountAdmin", // The user the role is assigned to. See the Users API for details. "user": null, // The status of the account role/user assignment. "workflow_state": "deleted" } ``` ## [List account admins](#method.admins.index) [AdminsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/admins_controller.rb) #### `GET /api/v1/accounts/:account_id/admins` **Scope:** `url:GET|/api/v1/accounts/:account_id/admins` A paginated list of the admins in the account #### Request Parameters: | Parameter | Type | Description | | ----------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- | | `user_id[]` | `[Integer]` | Scope the results to those with user IDs equal to any of the IDs specified here. | | `search_term` | `string` | The partial name or full ID of the admins to match and return in theresults list. Must be at least 2 characters. | | `include_deleted` | `boolean` | When set to true, returns admins who have been deleted | Returns a list of [Admin](#admin) objects. ## [Make an account admin](#method.admins.create) [AdminsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/admins_controller.rb) #### `POST /api/v1/accounts/:account_id/admins` **Scope:** `url:POST|/api/v1/accounts/:account_id/admins` Flag an existing user as an admin within the account. #### Request Parameters: | Parameter | Type | Description | | ------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | Required `integer` | The id of the user to promote. | | `role` | `string` | \[DEPRECATED] The user's admin relationship with the account will becreated with the given role. Defaults to 'AccountAdmin'. | | `role_id` | `integer` | The user's admin relationship with the account will be created with the given role. Defaults to the built-in role for 'AccountAdmin'. | | `send_confirmation` | `boolean` | Send a notification email tothe new admin if true. Default is true. | Returns an [Admin](#admin) object. ## [Remove account admin](#method.admins.destroy) [AdminsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/admins_controller.rb) #### `DELETE /api/v1/accounts/:account_id/admins/:user_id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/admins/:user_id` Remove the rights associated with an account admin role from a user. #### Request Parameters: | Parameter | Type | Description | | --------- | ------------------ | ------------------------------------------------------------------------------- | | `role` | `string` | \[DEPRECATED] Account role to remove from the user. | | `role_id` | Required `integer` | The id of the role representing the user's admin relationship with the account. | Returns an [Admin](#admin) object. ## [List my admin roles](#method.admins.self_roles) [AdminsController#self\_roles](https://github.com/instructure/canvas-lms/blob/master/app/controllers/admins_controller.rb) #### `GET /api/v1/accounts/:account_id/admins/self` **Scope:** `url:GET|/api/v1/accounts/:account_id/admins/self` A paginated list of the current user's roles in the account. The results are the same as those returned by the [List account admins](#method.admins.index) endpoint with +user\_id+ set to +self+, except the "Admins - Add / Remove" permission is not required. Returns a list of [Admin](#admin) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # AI Conversations API for managing conversations with AI Experiences. ## [Show conversation](#method.ai_conversations.show) [AiConversationsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id` Get a specific conversation by ID (for teachers viewing student conversations) ## [Get active conversation](#method.ai_conversations.active_conversation) [AiConversationsController#active\_conversation](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations` Get the active conversation for the current user and AI experience ## [Create AI conversation](#method.ai_conversations.create) [AiConversationsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations` Initialize a new conversation with the AI experience ## [Post message to conversation](#method.ai_conversations.post_message) [AiConversationsController#post\_message](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages` Send a message to an existing conversation and get the AI response #### Request Parameters: | Parameter | Type | Description | | --------- | ----------------- | ------------------------------------ | | `message` | Required `string` | The user's message to send to the AI | ## [Delete AI conversation](#method.ai_conversations.destroy) [AiConversationsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `DELETE /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id` End the current conversation session ## [Get conversation evaluation](#method.ai_conversations.evaluation) [AiConversationsController#evaluation](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/evaluation` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/evaluation` Fetch the latest stored evaluation for a conversation from the llm-conversation service. Reads only — does not run the LLM and is not rate-limited. `evaluation` is null when none has been generated yet (llma returns 200 + null, never 404, so this is distinguishable from an outage). `stale` is true when the AI experience was edited after the stored evaluation was generated. ## [Generate conversation evaluation](#method.ai_conversations.create_evaluation) [AiConversationsController#create\_evaluation](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/evaluation` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/evaluation` Run the LLM to (re)generate an evaluation for a conversation and persist it in the llm-conversation service. Rate-limited. Also the Reset path — a fresh run replaces any prior stored evaluation. ## [Create feedback on a conversation message](#method.ai_conversations.create_feedback) [AiConversationsController#create\_feedback](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages/:message_id/feedback` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages/:message_id/feedback` Submit a like or dislike vote on an AI-generated message. Ownership: load\_conversation gates this action — only the conversation owner or a course manager reaches here. Sub-resource (message\_id within the conversation) scoping is delegated to llma. #### Request Parameters: | Parameter | Type | Description | | ------------------ | ----------------- | ----------------------------- | | `vote` | Required `string` | "liked" or "disliked" | | `message_id` | Required `string` | llm-conversation message UUID | | `feedback_message` | `string` | optional text for dislike | ## [Delete feedback on a conversation message](#method.ai_conversations.delete_feedback) [AiConversationsController#delete\_feedback](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `DELETE /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages/:message_id/feedback/:feedback_id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages/:message_id/feedback/:feedback_id` Remove a previously submitted vote (toggling off like/dislike). Ownership: load\_conversation gates this action — only the conversation owner or a course manager reaches here. Sub-resource (message\_id, feedback\_id within the conversation) scoping is delegated to llma. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # AI Experiences API for creating, accessing and updating AI Experiences. AI Experiences are used to create interactive AI-powered learning scenarios within courses. #### An AiExperience object looks like: ```js // An AI Experience for interactive learning { // The ID of the AI experience "id": 234, // The title for the AI experience "title": "Customer Service Simulation", // The description of the AI experience "description": "Practice customer service skills in a simulated environment", // The AI facts for the experience (optional) "facts": "You are a customer service representative...", // The learning objectives for this experience "learning_objective": "Students will practice active listening and problem-solving", // The pedagogical guidance for the experience "pedagogical_guidance": "A customer is calling about a billing issue", // The current published state of the AI experience "workflow_state": "published", // The course this experience belongs to "course_id": 1578941 } ``` ## [List AI experiences](#method.ai_experiences.index) [AiExperiencesController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences` Retrieve the paginated list of AI experiences for a course #### Request Parameters: | Parameter | Type | Description | | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `workflow_state` | `string` | Only return experiences with the specified workflow state.Allowed values: published, unpublished, deleted | Returns a list of [AiExperience](#aiexperience) objects. ## [Show an AI experience](#method.ai_experiences.show) [AiExperiencesController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:id` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id` Retrieve an AI experience by ID Returns an [AiExperience](#aiexperience) object. ## [Show new AI experience form](#method.ai_experiences.new) [AiExperiencesController#new](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/new` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/new` Display the form for creating a new AI experience ## [Show edit AI experience form](#method.ai_experiences.edit) [AiExperiencesController#edit](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:id/edit` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id/edit` Display the form for editing an existing AI experience ## [Create an AI experience](#method.ai_experiences.create) [AiExperiencesController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences` Create a new AI experience for the specified course #### Request Parameters: | Parameter | Type | Description | | ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | `title` | Required `string` | The title of the AI experience. | | `description` | `string` | The description of the AI experience. | | `facts` | `string` | The AI facts for the experience. | | `learning_objective` | Required `string` | The learning objectives for this experience. | | `pedagogical_guidance` | Required `string` | The pedagogical guidance for the experience. | | `workflow_state` | `string` | The initial state of the experience. Defaults to 'unpublished'.Allowed values: published, unpublished | Returns an [AiExperience](#aiexperience) object. ## [Update an AI experience](#method.ai_experiences.update) [AiExperiencesController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `PUT /api/v1/courses/:course_id/ai_experiences/:id` **Scope:** `url:PUT|/api/v1/courses/:course_id/ai_experiences/:id` Update an existing AI experience #### Request Parameters: | Parameter | Type | Description | | ---------------------- | ----------------- | ----------------------------------------------------------------------------- | | `title` | `string` | The title of the AI experience. | | `description` | `string` | The description of the AI experience. | | `facts` | `string` | The AI facts for the experience. | | `learning_objective` | Required `string` | The learning objectives for this experience. | | `pedagogical_guidance` | Required `string` | The pedagogical guidance for the experience. | | `workflow_state` | `string` | The state of the experience.Allowed values: published, unpublished | Returns an [AiExperience](#aiexperience) object. ## [Delete an AI experience](#method.ai_experiences.destroy) [AiExperiencesController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `DELETE /api/v1/courses/:course_id/ai_experiences/:id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/ai_experiences/:id` Delete an AI experience (soft delete - marks as deleted) Returns an [AiExperience](#aiexperience) object. ## [List student AI conversations](#method.ai_experiences.ai_conversations_index) [AiExperiencesController#ai\_conversations\_index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:id/ai_conversations` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id/ai_conversations` Retrieve the latest AI conversation for each student in the course for this AI experience. Only available to teachers and course managers. ## [Show student AI conversation](#method.ai_experiences.ai_conversation_show) [AiExperiencesController#ai\_conversation\_show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:id/ai_conversations/:conversation_id` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id/ai_conversations/:conversation_id` Retrieve a specific student's AI conversation with full message history. Only available to teachers and course managers. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Analytics API for retrieving the data exposed in Canvas Analytics ## [Get department-level participation data](#method.analytics_api.department_participation) #### `GET /api/v1/accounts/:account_id/analytics/terms/:term_id/activity` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/activity` #### `GET /api/v1/accounts/:account_id/analytics/current/activity` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/current/activity` #### `GET /api/v1/accounts/:account_id/analytics/completed/activity` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/completed/activity` Returns page view hits summed across all courses in the department. Two groupings of these counts are returned; one by day (+by\_date+), the other by category (+by\_category+). The possible categories are announcements, assignments, collaborations, conferences, discussions, files, general, grades, groups, modules, other, pages, and quizzes. This and the other department-level endpoints have three variations which all return the same style of data but for different subsets of courses. All share the prefix /api/v1/accounts/\/analytics. The possible suffixes are: * /current: includes all available courses in the default term * /completed: includes all concluded courses in the default term * /terms/\: includes all available or concluded courses in the given term. Courses not yet offered or which have been deleted are never included. /current and /completed are intended for use when the account has only one term. /terms/\ is intended for use when the account has multiple terms. The action follows the suffix. #### Example Request: ```bash curl https:///api/v1/accounts//analytics/current/activity \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/completed/activity \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/terms//activity \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "by_date": { "2012-01-24": 1240, "2012-01-27": 912, }, "by_category": { "announcements": 54, "assignments": 256, "collaborations": 18, "conferences": 26, "discussions": 354, "files": 132, "general": 59, "grades": 177, "groups": 132, "modules": 71, "other": 412, "pages": 105, "quizzes": 356 }, } ``` ## [Get department-level grade data](#method.analytics_api.department_grades) #### `GET /api/v1/accounts/:account_id/analytics/terms/:term_id/grades` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/grades` #### `GET /api/v1/accounts/:account_id/analytics/current/grades` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/current/grades` #### `GET /api/v1/accounts/:account_id/analytics/completed/grades` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/completed/grades` Returns the distribution of grades for students in courses in the department. Each data point is one student's current grade in one course; if a student is in multiple courses, he contributes one value per course, but if he's enrolled multiple times in the same course (e.g. a lecture section and a lab section), he only constributes on value for that course. Grades are binned to the nearest integer score; anomalous grades outside the 0 to 100 range are ignored. The raw counts are returned, not yet normalized by the total count. Shares the same variations on endpoint as the participation data. #### Example Request: ```bash curl https:///api/v1/accounts//analytics/current/grades \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/completed/grades \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/terms//grades \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "0": 95, "1": 1, "2": 0, "3": 0, ... "93": 125, "94": 110, "95": 142, "96": 157, "97": 116, "98": 85, "99": 63, "100": 190 } ``` ## [Get department-level statistics](#method.analytics_api.department_statistics) #### `GET /api/v1/accounts/:account_id/analytics/terms/:term_id/statistics` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/statistics` #### `GET /api/v1/accounts/:account_id/analytics/current/statistics` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/current/statistics` #### `GET /api/v1/accounts/:account_id/analytics/completed/statistics` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/completed/statistics` Returns numeric statistics about the department and term (or filter). Shares the same variations on endpoint as the participation data. #### Example Request: ```bash curl https:///api/v1/accounts//analytics/current/statistics \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/completed/statistics \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/terms//statistics \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "courses": 27, "subaccounts": 3, "teachers": 36, "students": 418, "discussion_topics": 77, "media_objects": 219, "attachments": 1268, "assignments": 290, } ``` ## [Get department-level statistics, broken down by subaccount](#method.analytics_api.department_statistics_by_subaccount) #### `GET /api/v1/accounts/:account_id/analytics/terms/:term_id/statistics_by_subaccount` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/statistics_by_subaccount` #### `GET /api/v1/accounts/:account_id/analytics/current/statistics_by_subaccount` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/current/statistics_by_subaccount` #### `GET /api/v1/accounts/:account_id/analytics/completed/statistics_by_subaccount` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/completed/statistics_by_subaccount` Returns numeric statistics about the department subaccounts and term (or filter). Shares the same variations on endpoint as the participation data. #### Example Request: ```bash curl https:///api/v1/accounts//analytics/current/statistics_by_subaccount \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/completed/statistics_by_subaccount \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/terms//statistics_by_subaccount \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js {"accounts": [ { "name": "some string", "id": 188, "courses": 27, "teachers": 36, "students": 418, "discussion_topics": 77, "media_objects": 219, "attachments": 1268, "assignments": 290, } ]} ``` ## [Get course-level participation data](#method.analytics_api.course_participation) #### `GET /api/v1/courses/:course_id/analytics/activity` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/activity` Returns page view hits and participation numbers grouped by day through the entire history of the course. Page views is returned as a hash, where the hash keys are dates in the format "YYYY-MM-DD". The page\_views result set includes page views broken out by access category. Participations is returned as an array of dates in the format "YYYY-MM-DD". #### Example Request: ```bash curl https:///api/v1/courses//analytics/activity \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [ { "date": "2012-01-24", "participations": 3, "views": 10 } ] ``` ## [Get course-level assignment data](#method.analytics_api.course_assignments) #### `GET /api/v1/courses/:course_id/analytics/assignments` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/assignments` Returns a list of assignments for the course sorted by due date. For each assignment returns basic assignment information, the grade breakdown, and a breakdown of on-time/late status of homework submissions. #### Request Parameters: | Parameter | Type | Description | | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `async` | `boolean` | If async is true, then the course\_assignments call can happen asynch-ronously and MAY return a response containing a progress\_url key insteadof an assignments array. If it does, then it is the caller'sresponsibility to poll the API again to see if the progress is complete.If the data is ready (possibly even on the first async call) then itwill be passed back normally, as documented in the example response. | #### Example Request: ```bash curl https:///api/v1/courses//analytics/assignments \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [ { "assignment_id": 1234, "title": "Assignment 1", "points_possible": 10, "due_at": "2012-01-25T22:00:00-07:00", "unlock_at": "2012-01-20T22:00:00-07:00", "muted": false, "min_score": 2, "max_score": 10, "median": 7, "first_quartile": 4, "third_quartile": 8, "tardiness_breakdown": { "on_time": 0.75, "missing": 0.1, "late": 0.15 } }, { "assignment_id": 1235, "title": "Assignment 2", "points_possible": 15, "due_at": "2012-01-26T22:00:00-07:00", "unlock_at": null, "muted": true, "min_score": 8, "max_score": 8, "median": 8, "first_quartile": 8, "third_quartile": 8, "tardiness_breakdown": { "on_time": 0.65, "missing": 0.12, "late": 0.23 "total": 275 } } ] ``` ## [Get course-level student summary data](#method.analytics_api.course_student_summaries) #### `GET /api/v1/courses/:course_id/analytics/student_summaries` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/student_summaries` Returns a summary of per-user access information for all students in a course. This includes total page views, total participations, and a breakdown of on-time/late status for all homework submissions in the course. Each student's summary also includes the maximum number of page views and participations by any student in the course, which may be useful for some visualizations (since determining maximums client side can be tricky with pagination). #### Request Parameters: | Parameter | Type | Description | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sort_column` | `string` | The order results in which results are returned. Defaults to "name". Allowed values: `name`, `name_descending`, `score`, `score_descending`, `participations`, `participations_descending`, `page_views`, `page_views_descending` | | `student_id` | `string` | If set, returns only the specified student. | #### Example Request: ```bash curl https:///api/v1/courses//analytics/student_summaries \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [ { "id": 2346, "page_views": 351, "page_views_level": "1" "max_page_view": 415, "participations": 1, "participations_level": "3", "max_participations": 10, "tardiness_breakdown": { "total": 5, "on_time": 3, "late": 0, "missing": 2, "floating": 0 } }, { "id": 2345, "page_views": 124, "participations": 15, "tardiness_breakdown": { "total": 5, "on_time": 1, "late": 2, "missing": 3, "floating": 0 } } ] ``` ## [Get user-in-a-course-level participation data](#method.analytics_api.student_in_course_participation) #### `GET /api/v1/courses/:course_id/analytics/users/:student_id/activity` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/activity` Returns page view hits grouped by hour, and participation details through the entire history of the course. `page_views` are returned as a hash, where the keys are iso8601 dates, bucketed by the hour. `participations` are returned as an array of hashes, sorted oldest to newest. #### Example Request: ```bash curl https:///api/v1/courses//analytics/users//activity \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "page_views": { "2012-01-24T13:00:00-00:00": 19, "2012-01-24T14:00:00-00:00": 13, "2012-01-27T09:00:00-00:00": 23 }, "participations": [ { "created_at": "2012-01-21T22:00:00-06:00", "url": "https://canvas.example.com/path/to/canvas", }, { "created_at": "2012-01-27T22:00:00-06:00", "url": "https://canvas.example.com/path/to/canvas", } ] } ``` ## [Get user-in-a-course-level assignment data](#method.analytics_api.student_in_course_assignments) #### `GET /api/v1/courses/:course_id/analytics/users/:student_id/assignments` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/assignments` Returns a list of assignments for the course sorted by due date. For each assignment returns basic assignment information, the grade breakdown (including the student's actual grade), and the basic submission information for the student's submission if it exists. #### Example Request: ```bash curl https:///api/v1/courses//analytics/users//assignments \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [ { "assignment_id": 1234, "title": "Assignment 1", "points_possible": 10, "due_at": "2012-01-25T22:00:00-07:00", "unlock_at": "2012-01-20T22:00:00-07:00", "muted": false, "min_score": 2, "max_score": 10, "median": 7, "first_quartile": 4, "third_quartile": 8, "module_ids": [ 1, 2 ], "submission": { "posted_at": "2012-01-23T20:00:00-07:00", "submitted_at": "2012-01-22T22:00:00-07:00", "score": 10 } }, { "assignment_id": 1235, "title": "Assignment 2", "points_possible": 15, "due_at": "2012-01-26T22:00:00-07:00", "unlock_at": null, "muted": true, "min_score": 8, "max_score": 8, "median": 8, "first_quartile": 8, "third_quartile": 8, "module_ids": [ 1 ], "submission": { "posted_at": null, "submitted_at": "2012-01-22T22:00:00-07:00" } } ] ``` ## [Get user-in-a-course-level messaging data](#method.analytics_api.student_in_course_messaging) #### `GET /api/v1/courses/:course_id/analytics/users/:student_id/communication` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/communication` Returns messaging "hits" grouped by day through the entire history of the course. Returns a hash containing the number of instructor-to-student messages, and student-to-instructor messages, where the hash keys are dates in the format "YYYY-MM-DD". Message hits include Conversation messages and comments on homework submissions. #### Example Request: ```bash curl https:///api/v1/courses//analytics/users//communication \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "2012-01-24":{ "instructorMessages":1, "studentMessages":2 }, "2012-01-27":{ "studentMessages":1 } } ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Announcement External Feeds External feeds represent RSS feeds that can be attached to a Course or Group, in order to automatically create announcements for each new item in the feed. #### An ExternalFeed object looks like: ```js { // The ID of the feed "id": 5, // The title of the feed, pulled from the feed itself. If the feed hasn't yet // been pulled, a temporary name will be synthesized based on the URL "display_name": "My Blog", // The HTTP/HTTPS URL to the feed "url": "http://example.com/myblog.rss", // If not null, only feed entries whose title contains this string will trigger // new posts in Canvas "header_match": "pattern", // When this external feed was added to Canvas "created_at": "2012-06-01T00:00:00-06:00", // The verbosity setting determines how much of the feed's content is imported // into Canvas as part of the posting. 'link_only' means that only the title and // a link to the item. 'truncate' means that a summary of the first portion of // the item body will be used. 'full' means that the full item body will be // used. "verbosity": "truncate" } ``` ## [List external feeds](#method.external_feeds.index) [ExternalFeedsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/external_feeds_controller.rb) #### `GET /api/v1/courses/:course_id/external_feeds` **Scope:** `url:GET|/api/v1/courses/:course_id/external_feeds` #### `GET /api/v1/groups/:group_id/external_feeds` **Scope:** `url:GET|/api/v1/groups/:group_id/external_feeds` Returns the paginated list of External Feeds this course or group. #### Example Request: ```bash curl https:///api/v1/courses//external_feeds \ -H 'Authorization: Bearer ' ``` Returns a list of [ExternalFeed](#externalfeed) objects. ## [Create an external feed](#method.external_feeds.create) [ExternalFeedsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/external_feeds_controller.rb) #### `POST /api/v1/courses/:course_id/external_feeds` **Scope:** `url:POST|/api/v1/courses/:course_id/external_feeds` #### `POST /api/v1/groups/:group_id/external_feeds` **Scope:** `url:POST|/api/v1/groups/:group_id/external_feeds` Create a new external feed for the course or group. #### Request Parameters: | Parameter | Type | Description | | -------------- | ----------------- | ------------------------------------------------------------------------------------ | | `url` | Required `string` | The url to the external rss or atom feed | | `header_match` | `boolean` | If given, only feed entries that contain this string in their title will be imported | | `verbosity` | `string` | Defaults to "full" Allowed values: `full`, `truncate`, `link_only` | #### Example Request: ```bash curl https:///api/v1/courses//external_feeds \ -F url='http://example.com/rss.xml' \ -F header_match='news flash!' \ -F verbosity='full' \ -H 'Authorization: Bearer ' ``` Returns an [ExternalFeed](#externalfeed) object. ## [Delete an external feed](#method.external_feeds.destroy) [ExternalFeedsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/external_feeds_controller.rb) #### `DELETE /api/v1/courses/:course_id/external_feeds/:external_feed_id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/external_feeds/:external_feed_id` #### `DELETE /api/v1/groups/:group_id/external_feeds/:external_feed_id` **Scope:** `url:DELETE|/api/v1/groups/:group_id/external_feeds/:external_feed_id` Deletes the external feed. #### Example Request: ```bash curl -X DELETE https:///api/v1/courses//external_feeds/ \ -H 'Authorization: Bearer ' ``` Returns an [ExternalFeed](#externalfeed) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Announcements API for retrieving announcements. This API is Announcement-specific. See also the Discussion Topics API, which operates on Announcements also. ## [List announcements](#method.announcements_api.index) [AnnouncementsApiController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/announcements_api_controller.rb) #### `GET /api/v1/announcements` **Scope:** `url:GET|/api/v1/announcements` Returns the paginated list of announcements for the given courses and date range. Note that a +context\_code+ field is added to the responses so you can tell which course each announcement belongs to. #### Request Parameters: | Parameter | Type | Description | | ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `context_codes[]` | Required `string` | List of context\_codes to retrieve announcements for (for example, +course\_123+). Only coursesare presently supported. The call will fail unless the caller has View Announcements permissionin all listed courses. | | `start_date` | `Date` | Only return announcements posted since the start\_date (inclusive).Defaults to 14 days ago. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. | | `end_date` | `Date` | Only return announcements posted before the end\_date (inclusive).Defaults to 28 days from start\_date. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.Announcements scheduled for future posting will only be returned to course administrators. | | `available_after` | `Date` | Only return announcements having locked\_at nil or after available\_after (exclusive).The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.Effective only for students (who don't have moderate forum right). | | `active_only` | `boolean` | Only return active announcements that have been published.Applies only to requesting users that have permission to viewunpublished items.Defaults to false for users with access to view unpublished items,otherwise true and unmodifiable. | | `latest_only` | `boolean` | Only return the latest announcement for each associated context.The response will include at most one announcement for eachspecified context in the context\_codes\[] parameter.Defaults to false. | | `include` | `array` | Optional list of resources to include with the response. May includea string of the name of the resource. Possible values are:"sections", "sections\_user\_count"if "sections" is passed, includes the course sections that are associatedwith the topic, if the topic is specific to certain sections of the course.If "sections\_user\_count" is passed, then:(a) If sections were asked for and the topic is specific to certaincourse sections sections, includes the number of users in eachsection. (as part of the section json asked for above)(b) Else, includes at the root level the total number of users in thetopic's context (group or course) that the topic applies to. | #### Example Request: ```bash curl https:///api/v1/announcements?context_codes[]=course_1&context_codes[]=course_2 \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [{ "id": 1, "title": "Hear ye", "message": "Henceforth, all assignments must be...", "posted_at": "2017-01-31T22:00:00Z", "delayed_post_at": null, "context_code": "course_2", ... }] ``` Returns a list of [DiscussionTopic](/services/canvas/resources/discussion_topics#discussiontopic) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # API Token Scopes {% hint style="warning" %} BETA: This API resource is not finalized, and there could be breaking changes before its final release. {% endhint %} API for retrieving API scopes #### A Scope object looks like: ```js { // The resource the scope is associated with "resource": "courses", // The localized resource name "resource_name": "Courses", // The controller the scope is associated to "controller": "courses", // The controller action the scope is associated to "action": "index", // The HTTP verb for the scope "verb": "GET", // The identifier for the scope "scope": "url:GET|/api/v1/courses" } ``` ## [List scopes](#method.scopes_api.index) [ScopesApiController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/scopes_api_controller.rb) {% hint style="warning" %} BETA: This API endpoint is not finalized, and there could be breaking changes before its final release. {% endhint %} #### `GET /api/v1/accounts/:account_id/scopes` **Scope:** `url:GET|/api/v1/accounts/:account_id/scopes` A list of scopes that can be applied to developer keys and access tokens. #### Request Parameters: | Parameter | Type | Description | | ---------- | -------- | ----------------------------------------------------------------------------------------------------- | | `group_by` | `string` | The attribute to group the scopes by. By default no grouping is done. Allowed values: `resource_name` | Returns a list of [Scope](#scope) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Appointment Groups API for creating, accessing and updating appointment groups. Appointment groups provide a way of creating a bundle of time slots that users can sign up for (e.g. "Office Hours" or "Meet with professor about Final Project"). Both time slots and reservations of time slots are stored as Calendar Events. #### An Appointment object looks like: ```js // Date and time for an appointment { // The appointment identifier. "id": 987, // Start time for the appointment "start_at": "2012-07-20T15:00:00-06:00", // End time for the appointment "end_at": "2012-07-20T15:00:00-06:00" } ``` #### An AppointmentGroup object looks like: ```js { // The ID of the appointment group "id": 543, // The title of the appointment group "title": "Final Presentation", // The start of the first time slot in the appointment group "start_at": "2012-07-20T15:00:00-06:00", // The end of the last time slot in the appointment group "end_at": "2012-07-20T17:00:00-06:00", // The text description of the appointment group "description": "Es muy importante", // The location name of the appointment group "location_name": "El Tigre Chino's office", // The address of the appointment group's location "location_address": "Room 234", // The number of participant who have reserved slots (see include[] argument) "participant_count": 2, // The start and end times of slots reserved by the current user as well as the // id of the calendar event for the reservation (see include[] argument) "reserved_times": [{"id":987,"start_at":"2012-07-20T15:00:00-06:00","end_at":"2012-07-20T15:00:00-06:00"}], // Boolean indicating whether observer users should be able to sign-up for an // appointment "allow_observer_signup": false, // The context codes (i.e. courses) this appointment group belongs to. Only // people in these courses will be eligible to sign up. "context_codes": ["course_123"], // The sub-context codes (i.e. course sections and group categories) this // appointment group is restricted to "sub_context_codes": [course_section_234], // Current state of the appointment group ('pending', 'active' or 'deleted'). // 'pending' indicates that it has not been published yet and is invisible to // participants. "workflow_state": "active", // Boolean indicating whether the current user needs to sign up for this // appointment group (i.e. it's reservable and the // min_appointments_per_participant limit has not been met by this user). "requiring_action": true, // Number of time slots in this appointment group "appointments_count": 2, // Calendar Events representing the time slots (see include[] argument) Refer to // the Calendar Events API for more information "appointments": [], // Newly created time slots (same format as appointments above). Only returned // in Create/Update responses where new time slots have been added "new_appointments": [], // Maximum number of time slots a user may register for, or null if no limit "max_appointments_per_participant": 1, // Minimum number of time slots a user must register for. If not set, users do // not need to sign up for any time slots "min_appointments_per_participant": 1, // Maximum number of participants that may register for each time slot, or null // if no limit "participants_per_appointment": 1, // 'private' means participants cannot see who has signed up for a particular // time slot, 'protected' means that they can "participant_visibility": "private", // Indicates how participants sign up for the appointment group, either as // individuals ('User') or in student groups ('Group'). Related to // sub_context_codes (i.e. 'Group' signups always have a single group category) "participant_type": "User", // URL for this appointment group (to update, delete, etc.) "url": "https://example.com/api/v1/appointment_groups/543", // URL for a user to view this appointment group "html_url": "http://example.com/appointment_groups/1", // When the appointment group was created "created_at": "2012-07-13T10:55:20-06:00", // When the appointment group was last updated "updated_at": "2012-07-13T10:55:20-06:00" } ``` ## [List appointment groups](#method.appointment_groups.index) [AppointmentGroupsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups` **Scope:** `url:GET|/api/v1/appointment_groups` Retrieve the paginated list of appointment groups that can be reserved or managed by the current user. #### Request Parameters: | Parameter | Type | Description | | --------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `scope` | `string` | Defaults to "reservable" Allowed values: `reservable`, `manageable` | | `context_codes[]` | `string` | Array of context codes used to limit returned results. | | `include_past_appointments` | `boolean` | Defaults to false. If true, includes past appointment groups | | `include[]` | `string` | Array of additional information to include."appointments":: calendar event time slots for this appointment group"child\_events":: reservations of those time slots"participant\_count":: number of reservations"reserved\_times":: the event id, start time and end time of reservationsthe current user has made)"all\_context\_codes":: all context codes associated with this appointment group Allowed values: appointments, child\_events, participant\_count, reserved\_times, all\_context\_codes | ## [Create an appointment group](#method.appointment_groups.create) [AppointmentGroupsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `POST /api/v1/appointment_groups` **Scope:** `url:POST|/api/v1/appointment_groups` Create and return a new appointment group. If new\_appointments are specified, the response will return a new\_appointments array (same format as appointments array, see "List appointment groups" action) #### Request Parameters: | Parameter | Type | Description | | ----------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `appointment_group[context_codes][]` | Required `string` | Array of context codes (courses, e.g. course\_1) this group should belinked to (1 or more). Users in the course(s) with appropriate permissionswill be able to sign up for this appointment group. | | `appointment_group[sub_context_codes][]` | `string` | Array of sub context codes (course sections or a single group category)this group should be linked to. Used to limit the appointment group toparticular sections. If a group category is specified, students will signup in groups and the participant\_type will be "Group" instead of "User". | | `appointment_group[title]` | Required `string` | Short title for the appointment group. | | `appointment_group[description]` | `string` | Longer text description of the appointment group. | | `appointment_group[location_name]` | `string` | Location name of the appointment group. | | `appointment_group[location_address]` | `string` | Location address. | | `appointment_group[publish]` | `boolean` | Indicates whether this appointment group should be published (i.e. madeavailable for signup). Once published, an appointment group cannot beunpublished. Defaults to false. | | `appointment_group[participants_per_appointment]` | `integer` | Maximum number of participants that may register for each time slot.Defaults to null (no limit). | | `appointment_group[min_appointments_per_participant]` | `integer` | Minimum number of time slots a user must register for. If not set, usersdo not need to sign up for any time slots. | | `appointment_group[max_appointments_per_participant]` | `integer` | Maximum number of time slots a user may register for. | | `appointment_group[new_appointments][X][]` | `string` | Nested array of start time/end time pairs indicating time slots for thisappointment group. Refer to the example request. | | `appointment_group[participant_visibility]` | `string` | "private":: participants cannot see who has signed up for a particulartime slot"protected":: participants can see who has signed up. Defaults to"private". Allowed values: private, protected | | `appointment_group[allow_observer_signup]` | `boolean` | Whether observer users can sign-up for an appointment. Defaults to false. | #### Example Request: ```bash curl 'https:///api/v1/appointment_groups.json' \ -X POST \ -F 'appointment_group[context_codes][]=course_123' \ -F 'appointment_group[sub_context_codes][]=course_section_234' \ -F 'appointment_group[title]=Final Presentation' \ -F 'appointment_group[participants_per_appointment]=1' \ -F 'appointment_group[min_appointments_per_participant]=1' \ -F 'appointment_group[max_appointments_per_participant]=1' \ -F 'appointment_group[new_appointments][0][]=2012-07-19T21:00:00Z' \ -F 'appointment_group[new_appointments][0][]=2012-07-19T22:00:00Z' \ -F 'appointment_group[new_appointments][1][]=2012-07-19T22:00:00Z' \ -F 'appointment_group[new_appointments][1][]=2012-07-19T23:00:00Z' \ -H "Authorization: Bearer " ``` ## [Get a single appointment group](#method.appointment_groups.show) [AppointmentGroupsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups/:id` **Scope:** `url:GET|/api/v1/appointment_groups/:id` Returns information for a single appointment group #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Array of additional information to include. See include\[] argument of"List appointment groups" action."child\_events":: reservations of time slots time slots"appointments":: will always be returned"all\_context\_codes":: all context codes associated with this appointment group Allowed values: child\_events, appointments, all\_context\_codes | ## [Update an appointment group](#method.appointment_groups.update) [AppointmentGroupsController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `PUT /api/v1/appointment_groups/:id` **Scope:** `url:PUT|/api/v1/appointment_groups/:id` Update and return an appointment group. If new\_appointments are specified, the response will return a new\_appointments array (same format as appointments array, see "List appointment groups" action). #### Request Parameters: | Parameter | Type | Description | | ----------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `appointment_group[context_codes][]` | Required `string` | Array of context codes (courses, e.g. course\_1) this group should belinked to (1 or more). Users in the course(s) with appropriate permissionswill be able to sign up for this appointment group. | | `appointment_group[sub_context_codes][]` | `string` | Array of sub context codes (course sections or a single group category)this group should be linked to. Used to limit the appointment group toparticular sections. If a group category is specified, students will signup in groups and the participant\_type will be "Group" instead of "User". | | `appointment_group[title]` | `string` | Short title for the appointment group. | | `appointment_group[description]` | `string` | Longer text description of the appointment group. | | `appointment_group[location_name]` | `string` | Location name of the appointment group. | | `appointment_group[location_address]` | `string` | Location address. | | `appointment_group[publish]` | `boolean` | Indicates whether this appointment group should be published (i.e. madeavailable for signup). Once published, an appointment group cannot beunpublished. Defaults to false. | | `appointment_group[participants_per_appointment]` | `integer` | Maximum number of participants that may register for each time slot.Defaults to null (no limit). | | `appointment_group[min_appointments_per_participant]` | `integer` | Minimum number of time slots a user must register for. If not set, usersdo not need to sign up for any time slots. | | `appointment_group[max_appointments_per_participant]` | `integer` | Maximum number of time slots a user may register for. | | `appointment_group[new_appointments][X][]` | `string` | Nested array of start time/end time pairs indicating time slots for thisappointment group. Refer to the example request. | | `appointment_group[participant_visibility]` | `string` | "private":: participants cannot see who has signed up for a particulartime slot"protected":: participants can see who has signed up. Defaults to "private". Allowed values: private, protected | | `appointment_group[allow_observer_signup]` | `boolean` | Whether observer users can sign-up for an appointment. | #### Example Request: ```bash curl 'https:///api/v1/appointment_groups/543.json' \ -X PUT \ -F 'appointment_group[publish]=1' \ -H "Authorization: Bearer " ``` ## [Delete an appointment group](#method.appointment_groups.destroy) [AppointmentGroupsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `DELETE /api/v1/appointment_groups/:id` **Scope:** `url:DELETE|/api/v1/appointment_groups/:id` Delete an appointment group (and associated time slots and reservations) and return the deleted group #### Request Parameters: | Parameter | Type | Description | | --------------- | -------- | ---------------------------------------------------- | | `cancel_reason` | `string` | Reason for deleting/canceling the appointment group. | #### Example Request: ```bash curl 'https:///api/v1/appointment_groups/543.json' \ -X DELETE \ -F 'cancel_reason=El Tigre Chino got fired' \ -H "Authorization: Bearer " ``` ## [List user participants](#method.appointment_groups.users) [AppointmentGroupsController#users](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups/:id/users` **Scope:** `url:GET|/api/v1/appointment_groups/:id/users` A paginated list of users that are (or may be) participating in this appointment group. Refer to the Users API for the response fields. Returns no results for appointment groups with the "Group" participant\_type. #### Request Parameters: | Parameter | Type | Description | | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `registration_status` | `string` | Limits results to the a given participation status, defaults to "all" Allowed values: `all`, `registered`, `registered` | ## [List student group participants](#method.appointment_groups.groups) [AppointmentGroupsController#groups](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups/:id/groups` **Scope:** `url:GET|/api/v1/appointment_groups/:id/groups` A paginated list of student groups that are (or may be) participating in this appointment group. Refer to the Groups API for the response fields. Returns no results for appointment groups with the "User" participant\_type. #### Request Parameters: | Parameter | Type | Description | | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `registration_status` | `string` | Limits results to the a given participation status, defaults to "all" Allowed values: `all`, `registered`, `registered` | ## [Get next appointment](#method.appointment_groups.next_appointment) [AppointmentGroupsController#next\_appointment](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups/next_appointment` **Scope:** `url:GET|/api/v1/appointment_groups/next_appointment` Return the next appointment available to sign up for. The appointment is returned in a one-element array. If no future appointments are available, an empty array is returned. #### Request Parameters: | Parameter | Type | Description | | ------------------------- | -------- | -------------------------------------------- | | `appointment_group_ids[]` | `string` | List of ids of appointment groups to search. | Returns a list of [CalendarEvent](/services/canvas/resources/calendar_events#calendarevent) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Assessment Question Banks #### An AssessmentQuestionBank object looks like: ```js { // The ID of the assessment question bank. "id": 1, // The ID of the context (course or account) the question bank belongs to. "context_id": 2, // The type of context (Course or Account). "context_type": "Course", // The title of the question bank. "title": "Chapter 1 Questions", // The workflow state of the question bank. "workflow_state": "active", // The number of questions in the bank. "assessment_question_count": 10, // The combined context type and ID. "context_code": "course_2", // The date and time the question bank was created. "created_at": "2013-01-01T00:00:00Z", // The date and time the question bank was last updated. "updated_at": "2013-01-01T00:00:00Z" } ``` #### An AssessmentQuestion object looks like: ```js { // The ID of the assessment question. "id": 1, // The order of the question. "position": 1, // The ID of the question bank this question belongs to. "assessment_question_bank_id": 3, // The date and time when the assessment question was created. "created_at": "2013-01-23T23:59:00-07:00", // The name of the question. "question_name": "Prime Number Identification", // The type of the question. "question_type": "multiple_choice_question", // The text of the question. "question_text": "Which of the following is NOT a prime number?", // The maximum amount of points possible received for getting this question // correct. "points_possible": 5, // The comments to display if the student answers the question correctly. "correct_comments": "That's correct!", // The comments to display if the student answers incorrectly. "incorrect_comments": "Unfortunately, that IS a prime number.", // The comments to display regardless of how the student answered. "neutral_comments": "Goldbach's conjecture proposes that every even integer greater than 2 can be expressed as the sum of two prime numbers.", // The HTML version of the comments to display if the student answers the // question correctly. "correct_comments_html": "That's correct!", // The HTML version of the comments to display if the student answers // incorrectly. "incorrect_comments_html": "Unfortunately, that IS a prime number.", // The HTML version of the comments to display regardless of how the student // answered. "neutral_comments_html": "Goldbach's conjecture proposes that every even integer greater than 2 can be expressed as the sum of two prime numbers.", // An array of available answers. Each answer contains id, text, html, comments, // comments_html, and weight properties. "answers": null, // Variables for calculated questions. Null for other question types. "variables": null, // Formulas for calculated questions. Null for other question types. "formulas": null, // The tolerance for numerical answers. Null for non-numerical question types. "answer_tolerance": null, // The number of decimal places for formula results. Null for non-calculated // question types. "formula_decimal_places": null, // Matching pairs for matching questions. Null for other question types. "matches": null, // Incorrect match options for matching questions. Null for other question // types. "matching_answer_incorrect_matches": null } ``` ## [List question banks](#method.assessment_question_banks.index) [AssessmentQuestionBanksController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assessment_question_banks_controller.rb) #### `GET /api/v1/question_banks` **Scope:** `url:GET|/api/v1/question_banks` Returns the paginated list of question banks for a given context. #### Request Parameters: | Parameter | Type | Description | | ------------------------ | ------------------ | ---------------------------------------------------------------------------------------------- | | `context_type` | Required `string` | The type of context. Must be either "Course" or "Account". Allowed values: `Course`, `Account` | | `context_id` | Required `integer` | The id of the context. | | `include_question_count` | `boolean` | Whether to include the number of questions in each bank. | #### Example Request: ```bash curl 'https:///api/v1/question_banks?context_type=Course&context_id=1' \ -H 'Authorization: Bearer ' ``` Returns a list of [AssessmentQuestionBank](#assessmentquestionbank) objects. ## [Get a single question bank](#method.assessment_question_banks.show) [AssessmentQuestionBanksController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assessment_question_banks_controller.rb) #### `GET /api/v1/question_banks/:id` **Scope:** `url:GET|/api/v1/question_banks/:id` Returns the question bank with the given id #### Request Parameters: | Parameter | Type | Description | | ------------------------ | ------------------ | ------------------------------------------------------- | | `id` | Required `integer` | The question bank unique identifier. | | `include_question_count` | `boolean` | Whether to include the number of questions in the bank. | Returns an [AssessmentQuestionBank](#assessmentquestionbank) object. ## [List assessment questions for a question bank](#method.assessment_question_banks.questions) [AssessmentQuestionBanksController#questions](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assessment_question_banks_controller.rb) #### `GET /api/v1/question_banks/:id/questions` **Scope:** `url:GET|/api/v1/question_banks/:id/questions` Returns the paginated list of assessment questions in this bank. #### Request Parameters: | Parameter | Type | Description | | --------- | ------------------ | ------------------------------------ | | `id` | Required `integer` | The question bank unique identifier. | #### Example Request: ```bash curl 'https:///api/v1/question_banks/:id/questions' \ -H 'Authorization: Bearer ' ``` Returns a list of [AssessmentQuestion](#assessmentquestion) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Asset Processor 1EdTech Asset Processor services: Asset Service and Asset Report Service. 1EdTech Asset Processor services: Eula Service and Eula Acceptance Service. ## [Create an Asset Report](#method.lti/ims/asset_processor.create_report) [Lti::Ims::AssetProcessorController#create\_report](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/ims/asset_processor_controller.rb) #### `POST /api/lti/asset_processors/:asset_processor_id/reports` **Scope:** `url:POST|/api/lti/asset_processors/:asset_processor_id/reports` Creates a report for a given Canvas-managed asset (such as a submission attachment). Returns an HTTP 201 (Created) on success. #### Request Parameters: | Parameter | Type | Description | | -------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `assetId` | `string` | The UUID of the asset to which the report applies. Canvas will supplythis to the tool in the the LtiAssetProcessorSubmissionNotice. | | `errorCode` | `string` | A machine-readable code indicating the cause of the failure, for reportswith a processingProgress value of Failed. The following standard errorcodes are available, but tools may use their own (in which case the toolmay provide human-readable information in the comment field):UNSUPPORTED\_ASSET\_TYPE, ASSET\_TOO\_LARGE, ASSET\_TOO\_SMALL,EULA\_NOT\_ACCEPTED, DOWNLOAD\_FAILED | | `indicationAlt` | `string` | Alternate text representing the meaning of the indicationColor for screenreaders or as a tooltip over the indication color. | | `indicationColor` | `string` | A hex (#RRGGBB) color code the tool wishes to use indicating the outcomeof an asset's report. | | `priority` | `integer` | A number from 0 (meaning "good" or "success") to 5 (meaning urgent ortime-critical notable features) indicating the tool's perceived priorityof the report. If a priority is not known or applicable, the tool shoulduse the value 0. | | `processingProgress` | `string` | Indicates the status of the report. Should be one of the following:Processed, Processing, PendingManual, Failed, NotProcessed, NotReady.If an unrecognized value is given, the value will be stored, but willbe treated by Canvas as NotReady. | | `result` | `string` | A short string (16 characters or fewer) that briefly describes thesuccessful result of the processing. This should be provided ifprocessingProgress is Processed, and not provided otherwise. | | `timestamp` | `string` | An ISO8601 date time value with microsecond precision. Reports with newertimestamps for the same asset and report type supersedepreviously submitted reports with older (or equal) timestamps. Likewise,if the timestamp provided is older than the latest timestamp for anexisting report (of same asset and type), the new report will beignored and the endpoint will return an HTTP 409 (Conflict). | | `title` | `string` | A human-readable title for the report, to be displayed to the user. | | `type` | `string` | An opaque value representing the type of report. | | `visibleToOwner` | `boolean` | A boolean value indicates whether the indicator and reportshould be visible to the user who owns the asset being reported on.If no value is provided, the platform should assume a default value of false | #### Example Request: ```bash { "assetId" : "57d463ea-6e5d-45c8-a86f-64f3dd9ef81e", "type": "originality", "timestamp": "2025-01-24T17:56:53.221+00:00", "title": "Originality Report", "result" : "75/100", "indicationColor" : "#EC0000", "indicationAlt" : "High percentage of matched text.", "priority": 5, "processingProgress": "Processed" } ``` ```bash { "assetId" : "57d463ea-6e5d-45c8-a86f-64f3dd9ef81e", "type": "originality", "timestamp": "2025-01-24T17:56:53.221+00:00", "title": "Originality Report", "priority": 0, "errorCode": "UNSUPPORTED_ASSET_TYPE", "processingProgress": "Failed" } ``` #### Example Response: ```js { "assetId" : "57d463ea-6e5d-45c8-a86f-64f3dd9ef81e", "type": "originality", "timestamp": "2025-01-24T17:56:53.221+00:00", "title": "Originality Report", "result" : "75/100", "indicationColor" : "#EC0000", "indicationAlt" : "High percentage of matched text.", "priority": 5, "processingProgress": "Processed" } ``` ## [Update Eula Deployment Configuration](#method.lti/ims/asset_processor_eula.update_tool_eula) [Lti::Ims::AssetProcessorEulaController#update\_tool\_eula](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/ims/asset_processor_eula_controller.rb) #### `PUT /api/lti/asset_processor_eulas/:context_external_tool_id/deployment` **Scope:** `url:PUT|/api/lti/asset_processor_eulas/:context_external_tool_id/deployment` Provides a mechanism by which a platform can enable or disable the requirement for users to accept a EULA within the scope of an entire deployment #### Request Parameters: | Parameter | Type | Description | | -------------- | --------- | ------------------------------------------------------------------------------------ | | `eulaRequired` | `boolean` | A boolean value representing whether or not the EULA is required for the deployment. | #### Example Request: ```bash { "eulaRequired": true, } ``` #### Example Response: ```js { "eulaRequired": true, } ``` ## [Create an Eula Acceptance](#method.lti/ims/asset_processor_eula.create_acceptance) [Lti::Ims::AssetProcessorEulaController#create\_acceptance](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/ims/asset_processor_eula_controller.rb) #### `POST /api/lti/asset_processor_eulas/:context_external_tool_id/user` **Scope:** `url:POST|/api/lti/asset_processor_eulas/:context_external_tool_id/user` The EULA user acceptance service provides a mechanism by which a tool can notify a platform of whether or not a user has accepted a EULA. #### Request Parameters: | Parameter | Type | Description | | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userId` | `string` | The userId represents the user who has accepted or declined the EULA,lti\_id of the Canvas User. | | `accepted` | `boolean` | A boolean value representing whether or not the user has accepted the EULA | | `timestamp` | `string` | The timestamp represents the time at which the user accepted or declined the EULA.This timestamp must be formatted as an ISO 8601 date time. | #### Example Request: ```bash { "userId": "59ed2101-0302-406c-b53f-9705ae1cb357", "accepted": true, "timestamp": "2022-04-16T18:54:36.736+00:00" } ``` #### Example Response: ```js { "userId": "59ed2101-0302-406c-b53f-9705ae1cb357", "accepted": true, "timestamp": "2022-04-16T18:54:36.736+00:00" } ``` ## [Delete Eula Acceptances for deployment](#method.lti/ims/asset_processor_eula.delete_acceptances) [Lti::Ims::AssetProcessorEulaController#delete\_acceptances](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/ims/asset_processor_eula_controller.rb) #### `DELETE /api/lti/asset_processor_eulas/:context_external_tool_id/user` **Scope:** `url:DELETE|/api/lti/asset_processor_eulas/:context_external_tool_id/user` Remove the EULA acceptance status for all users within the current deployment. This will allow a tool to reset the EULA acceptance status for all users, and force them to accept the EULA again in the case that the EULA has changed. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Assignment Extensions API for setting extensions on student assignment submissions. These cannot be set for discussion assignments or quizzes. For quizzes, use [Quiz Extensions](/services/canvas/resources/quiz_extensions) instead. #### An AssignmentExtension object looks like: ```js { // The ID of the Assignment the extension belongs to. "assignment_id": 2, // The ID of the Student that needs the assignment extension. "user_id": 3, // Number of times the student is allowed to re-submit the assignment "extra_attempts": 2 } ``` ## [Set extensions for student assignment submissions](#method.assignment_extensions.create) [AssignmentExtensionsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_extensions_controller.rb) #### `POST /api/v1/courses/:course_id/assignments/:assignment_id/extensions` **Scope:** `url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/extensions` \Responses\ * \200 OK\ if the request was successful * \403 Forbidden\ if you are not allowed to extend assignments for this course * \400 Bad Request\ if any of the extensions are invalid #### Request Parameters: | Parameter | Type | Description | | ----------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------ | | `assignment_extensions[][user_id]` | Required `integer` | The ID of the user we want to add assignment extensions for. | | `assignment_extensions[][extra_attempts]` | Required `integer` | Number of times the student is allowed to re-take the assignment over thelimit. | #### Example Request: ```bash { "assignment_extensions": [{ "user_id": 3, "extra_attempts": 2 },{ "user_id": 2, "extra_attempts": 2 }] } ``` #### Example Response: ```js { "assignment_extensions": [AssignmentExtension] } ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Assignment Groups API for accessing Assignment Group and Assignment information. #### A GradingRules object looks like: ```js { // Number of lowest scores to be dropped for each user. "drop_lowest": 1, // Number of highest scores to be dropped for each user. "drop_highest": 1, // Assignment IDs that should never be dropped. "never_drop": [33, 17, 24] } ``` #### An AssignmentGroup object looks like: ```js { // the id of the Assignment Group "id": 1, // the name of the Assignment Group "name": "group2", // the position of the Assignment Group "position": 7, // the weight of the Assignment Group "group_weight": 20, // the sis source id of the Assignment Group "sis_source_id": "1234", // the integration data of the Assignment Group "integration_data": {"5678":"0954"}, // the assignments in this Assignment Group (see the Assignment API for a // detailed list of fields) "assignments": [], // the grading rules that this Assignment Group has "rules": null } ``` ## [List assignment groups](#method.assignment_groups.index) [AssignmentGroupsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_controller.rb) #### `GET /api/v1/courses/:course_id/assignment_groups` **Scope:** `url:GET|/api/v1/courses/:course_id/assignment_groups` Returns the paginated list of assignment groups for the current context. The returned groups are sorted by their position field. #### Request Parameters: | Parameter | Type | Description | | --------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `include[]` | `string` | Associations to include with the group. "discussion\_topic", "all\_dates", "can\_edit","assignment\_visibility" & "submission" are only valid if "assignments" is also included."score\_statistics" requires that the "assignments" and "submission" options are included.The "assignment\_visibility" option additionally requires that the Differentiated Assignments course feature be turned on.If "observed\_users" is passed along with "assignments" and "submission", submissions for observed users will also be included as an array.The "peer\_review" option requires that the Peer Review Grading course feature be turned on and that "assignments" is included. Allowed values: assignments, discussion\_topic, all\_dates, assignment\_visibility, overrides, submission, observed\_users, can\_edit, score\_statistics, peer\_review | | `assignment_ids[]` | `string` | If "assignments" are included, optionally return only assignments having their ID in this array. This argument may also be passed asa comma separated string. | | `exclude_assignment_submission_types[]` | `string` | If "assignments" are included, those with the specified submission typeswill be excluded from the assignment groups. Allowed values: online\_quiz, discussion\_topic, wiki\_page, external\_tool | | `override_assignment_dates` | `boolean` | Apply assignment overrides for each assignment, defaults to true. | | `grading_period_id` | `integer` | The id of the grading period in which assignment groups are being requested(Requires grading periods to exist.) | | `scope_assignments_to_student` | `boolean` | If true, all assignments returned will apply to the current user in thespecified grading period. If assignments apply to other students in thespecified grading period, but not the current user, they will not bereturned. (Requires the grading\_period\_id argument and grading periods toexist. In addition, the current user must be a student.) | Returns a list of [AssignmentGroup](#assignmentgroup) objects. ## [Get an Assignment Group](#method.assignment_groups_api.show) [AssignmentGroupsApiController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_api_controller.rb) #### `GET /api/v1/courses/:course_id/assignment_groups/:assignment_group_id` **Scope:** `url:GET|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id` Returns the assignment group with the given id. #### Request Parameters: | Parameter | Type | Description | | --------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Associations to include with the group. "discussion\_topic" and "assignment\_visibility" and "submission"are only valid if "assignments" is also included. "score\_statistics" is only valid if "submission" and"assignments" are also included. The "assignment\_visibility" option additionally requires that the Differentiated Assignmentscourse feature be turned on. Allowed values: assignments, discussion\_topic, assignment\_visibility, submission, score\_statistics | | `override_assignment_dates` | `boolean` | Apply assignment overrides for each assignment, defaults to true. | | `grading_period_id` | `integer` | The id of the grading period in which assignment groups are being requested(Requires grading periods to exist on the account) | Returns an [AssignmentGroup](#assignmentgroup) object. ## [Create an Assignment Group](#method.assignment_groups_api.create) [AssignmentGroupsApiController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_api_controller.rb) #### `POST /api/v1/courses/:course_id/assignment_groups` **Scope:** `url:POST|/api/v1/courses/:course_id/assignment_groups` Create a new assignment group for this course. #### Request Parameters: | Parameter | Type | Description | | ------------------ | --------- | -------------------------------------------------------------------------------- | | `name` | `string` | The assignment group's name | | `position` | `integer` | The position of this assignment group in relation to the other assignment groups | | `group_weight` | `number` | The percent of the total grade that this assignment group represents | | `sis_source_id` | `string` | The sis source id of the Assignment Group | | `integration_data` | `Object` | The integration data of the Assignment Group | Returns an [AssignmentGroup](#assignmentgroup) object. ## [Edit an Assignment Group](#method.assignment_groups_api.update) [AssignmentGroupsApiController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_api_controller.rb) #### `PUT /api/v1/courses/:course_id/assignment_groups/:assignment_group_id` **Scope:** `url:PUT|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id` Modify an existing Assignment Group. #### Request Parameters: | Parameter | Type | Description | | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | The assignment group's name | | `position` | `integer` | The position of this assignment group in relation to the other assignment groups | | `group_weight` | `number` | The percent of the total grade that this assignment group represents | | `sis_source_id` | `string` | The sis source id of the Assignment Group | | `integration_data` | `Object` | The integration data of the Assignment Group | | `rules` | `string` | The grading rules that are applied within this assignment groupSee the Assignment Group object definition for format | Returns an [AssignmentGroup](#assignmentgroup) object. ## [Destroy an Assignment Group](#method.assignment_groups_api.destroy) [AssignmentGroupsApiController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_api_controller.rb) #### `DELETE /api/v1/courses/:course_id/assignment_groups/:assignment_group_id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id` Deletes the assignment group with the given id. #### Request Parameters: | Parameter | Type | Description | | --------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `move_assignments_to` | `integer` | The ID of an active Assignment Group to which the assignments that arecurrently assigned to the destroyed Assignment Group will be assigned.NOTE: If this argument is not provided, any assignments in this AssignmentGroup will be deleted. | Returns an [AssignmentGroup](#assignmentgroup) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Assignments API for accessing assignment information. #### An ExternalToolTagAttributes object looks like: ```js { // URL to the external tool "url": "http://instructure.com", // Whether or not there is a new tab for the external tool "new_tab": false, // the identifier for this tool_tag "resource_link_id": "ab81173af98b8c33e66a" } ``` #### A LockInfo object looks like: ```js { // Asset string for the object causing the lock "asset_string": "assignment_4", // (Optional) Time at which this was/will be unlocked. Must be before the due // date. "unlock_at": "2013-01-01T00:00:00-06:00", // (Optional) Time at which this was/will be locked. Must be after the due date. "lock_at": "2013-02-01T00:00:00-06:00", // (Optional) Context module causing the lock. "context_module": "{}", "manually_locked": true } ``` #### A RubricRating object looks like: ```js { "points": 10, "id": "rat1", "description": "Full marks", "long_description": "Student completed the assignment flawlessly." } ``` #### A RubricCriteria object looks like: ```js { "points": 10, // The id of rubric criteria. "id": "crit1", // (Optional) The id of the learning outcome this criteria uses, if any. "learning_outcome_id": "1234", // (Optional) The 3rd party vendor's GUID for the outcome this criteria // references, if any. "vendor_guid": "abdsfjasdfne3jsdfn2", "description": "Criterion 1", "long_description": "Criterion 1 more details", "criterion_use_range": true, "ratings": null, "ignore_for_scoring": true } ``` #### An AssignmentDate object looks like: ```js // Object representing a due date for an assignment or quiz. If the due date // came from an assignment override, it will have an 'id' field. { // (Optional, missing if 'base' is present) id of the assignment override this // date represents "id": 1, // (Optional, present if 'id' is missing) whether this date represents the // assignment's or quiz's default due date "base": true, "title": "Summer Session", // The due date for the assignment. Must be between the unlock date and the lock // date if there are lock dates "due_at": "2013-08-28T23:59:00-06:00", // The unlock date for the assignment. Must be before the due date if there is a // due date. "unlock_at": "2013-08-01T00:00:00-06:00", // The lock date for the assignment. Must be after the due date if there is a // due date. "lock_at": "2013-08-31T23:59:00-06:00" } ``` #### A TurnitinSettings object looks like: ```js { "originality_report_visibility": "after_grading", "s_paper_check": false, "internet_check": false, "journal_check": false, "exclude_biblio": false, "exclude_quoted": false, "exclude_small_matches_type": "percent", "exclude_small_matches_value": 50 } ``` #### A NeedsGradingCount object looks like: ```js // Used by Assignment model { // The section ID "section_id": "123456", // Number of submissions that need grading "needs_grading_count": 5 } ``` #### A ScoreStatistic object looks like: ```js // Used by Assignment model { // Min score "min": 1, // Max score "max": 10, // Mean score "mean": 6, // Upper quartile score "upper_q": 10, // Median score "median": 6, // Lower quartile score "lower_q": 1 } ``` #### An Assignment object looks like: ```js { // the ID of the assignment "id": 4, // the name of the assignment "name": "some assignment", // the assignment description, in an HTML fragment "description": "Do the following:...", // The time at which this assignment was originally created "created_at": "2012-07-01T23:59:00-06:00", // The time at which this assignment was last modified in any way "updated_at": "2012-07-01T23:59:00-06:00", // the due date for the assignment. returns null if not present. NOTE: If this // assignment has assignment overrides, this field will be the due date as it // applies to the user requesting information from the API. "due_at": "2012-07-01T23:59:00-06:00", // the lock date (assignment is locked after this date). returns null if not // present. NOTE: If this assignment has assignment overrides, this field will // be the lock date as it applies to the user requesting information from the // API. "lock_at": "2012-07-01T23:59:00-06:00", // the unlock date (assignment is unlocked after this date) returns null if not // present NOTE: If this assignment has assignment overrides, this field will be // the unlock date as it applies to the user requesting information from the // API. "unlock_at": "2012-07-01T23:59:00-06:00", // whether this assignment has overrides "has_overrides": true, // (Optional) all dates associated with the assignment, if applicable "all_dates": null, // the ID of the course the assignment belongs to "course_id": 123, // the URL to the assignment's web page "html_url": "https://...", // the URL to download all submissions as a zip "submissions_download_url": "https://example.com/courses/:course_id/assignments/:id/submissions?zip=1", // the ID of the assignment's group "assignment_group_id": 2, // Boolean flag indicating whether the assignment requires a due date based on // the account level setting "due_date_required": true, // Allowed file extensions, which take effect if submission_types includes // 'online_upload'. "allowed_extensions": ["docx", "ppt"], // An integer indicating the maximum length an assignment's name may be "max_name_length": 15, // Boolean flag indicating whether or not Turnitin has been enabled for the // assignment. NOTE: This flag will not appear unless your account has the // Turnitin plugin available "turnitin_enabled": true, // Boolean flag indicating whether or not VeriCite has been enabled for the // assignment. NOTE: This flag will not appear unless your account has the // VeriCite plugin available "vericite_enabled": true, // Settings to pass along to turnitin to control what kinds of matches should be // considered. originality_report_visibility can be 'immediate', // 'after_grading', 'after_due_date', or 'never' exclude_small_matches_type can // be null, 'percent', 'words' exclude_small_matches_value: - if type is null, // this will be null also - if type is 'percent', this will be a number between // 0 and 100 representing match size to exclude as a percentage of the document // size. - if type is 'words', this will be number > 0 representing how many // words a match must contain for it to be considered NOTE: This flag will not // appear unless your account has the Turnitin plugin available "turnitin_settings": null, // If this is a group assignment, boolean flag indicating whether or not // students will be graded individually. "grade_group_students_individually": false, // (Optional) assignment's settings for external tools if submission_types // include 'external_tool'. Only url and new_tab are included (new_tab defaults // to false). Use the 'External Tools' API if you need more information about // an external tool. "external_tool_tag_attributes": null, // Boolean indicating if peer reviews are required for this assignment "peer_reviews": false, // Boolean indicating peer reviews are assigned automatically. If false, the // teacher is expected to manually assign peer reviews. "automatic_peer_reviews": false, // Integer representing the amount of reviews each user is assigned. NOTE: This // key is NOT present unless you have automatic_peer_reviews set to true. "peer_review_count": 0, // String representing a date the reviews are due by. Must be a date that occurs // after the default due date. If blank, or date is not after the assignment's // due date, the assignment's due date will be used. NOTE: This key is NOT // present unless you have automatic_peer_reviews set to true. "peer_reviews_assign_at": "2012-07-01T23:59:00-06:00", // Boolean representing whether or not members from within the same group on a // group assignment can be assigned to peer review their own group's work "intra_group_peer_reviews": false, // The ID of the assignment’s group set, if this is a group assignment. For // group discussions, set group_category_id on the discussion topic, not the // linked assignment. "group_category_id": 1, // if the requesting user has grading rights, the number of submissions that // need grading. "needs_grading_count": 17, // if the requesting user has grading rights and the // 'needs_grading_count_by_section' flag is specified, the number of submissions // that need grading split out by section. NOTE: This key is NOT present unless // you pass the 'needs_grading_count_by_section' argument as true. ANOTHER // NOTE: it's possible to be enrolled in multiple sections, and if a student is // setup that way they will show an assignment that needs grading in multiple // sections (effectively the count will be duplicated between sections) "needs_grading_count_by_section": [{"section_id":"123456","needs_grading_count":5}, {"section_id":"654321","needs_grading_count":0}], // the sorting order of the assignment in the group "position": 1, // (optional, present if Sync Grades to SIS feature is enabled) "post_to_sis": true, // (optional, Third Party unique identifier for Assignment) "integration_id": "12341234", // (optional, Third Party integration data for assignment) "integration_data": {"5678":"0954"}, // the maximum points possible for the assignment "points_possible": 12.0, // the types of submissions allowed for this assignment list containing one or // more of the following: 'discussion_topic', 'online_quiz', 'on_paper', 'none', // 'external_tool', 'online_text_entry', 'online_url', 'online_upload', // 'media_recording', 'student_annotation' "submission_types": ["online_text_entry"], // If true, the assignment has been submitted to by at least one student "has_submitted_submissions": true, // The type of grading the assignment receives; one of 'pass_fail', 'percent', // 'letter_grade', 'gpa_scale', 'points' "grading_type": "points", // The id of the grading standard being applied to this assignment. Valid if // grading_type is 'letter_grade' or 'gpa_scale'. "grading_standard_id": null, // Whether the assignment is published "published": true, // Whether the assignment's 'published' state can be changed to false. Will be // false if there are student submissions for the assignment. "unpublishable": false, // Whether the assignment is only visible to overrides. "only_visible_to_overrides": false, // Whether or not this is locked for the user. "locked_for_user": false, // (Optional) Information for the user about the lock. Present when // locked_for_user is true. "lock_info": null, // (Optional) An explanation of why this is locked for the user. Present when // locked_for_user is true. "lock_explanation": "This assignment is locked until September 1 at 12:00am", // (Optional) id of the associated quiz (applies only when submission_types is // ['online_quiz']) "quiz_id": 620, // (Optional) whether anonymous submissions are accepted (applies only to quiz // assignments) "anonymous_submissions": false, // (Optional) the DiscussionTopic associated with the assignment, if applicable "discussion_topic": null, // (Optional) Boolean indicating if assignment will be frozen when it is copied. // NOTE: This field will only be present if the AssignmentFreezer plugin is // available for your account. "freeze_on_copy": false, // (Optional) Boolean indicating if assignment is frozen for the calling user. // NOTE: This field will only be present if the AssignmentFreezer plugin is // available for your account. "frozen": false, // (Optional) Array of frozen attributes for the assignment. Only account // administrators currently have permission to change an attribute in this list. // Will be empty if no attributes are frozen for this assignment. Possible // frozen attributes are: title, description, lock_at, points_possible, // grading_type, submission_types, assignment_group_id, allowed_extensions, // group_category_id, notify_of_update, peer_reviews NOTE: This field will only // be present if the AssignmentFreezer plugin is available for your account. "frozen_attributes": ["title"], // (Optional) If 'submission' is included in the 'include' parameter, includes a // Submission object that represents the current user's (user who is requesting // information from the api) current submission for the assignment. See the // Submissions API for an example response. If the user does not have a // submission, this key will be absent. "submission": null, // (Optional) If true, the rubric is directly tied to grading the assignment. // Otherwise, it is only advisory. Included if there is an associated rubric. "use_rubric_for_grading": true, // (Optional) An object describing the basic attributes of the rubric, including // the point total. Included if there is an associated rubric. "rubric_settings": {"points_possible":"12"}, // (Optional) A list of scoring criteria and ratings for each rubric criterion. // Included if there is an associated rubric. "rubric": null, // (Optional) If 'assignment_visibility' is included in the 'include' parameter, // includes an array of student IDs who can see this assignment. "assignment_visibility": [137, 381, 572], // (Optional) If 'overrides' is included in the 'include' parameter, includes an // array of assignment override objects. "overrides": null, // (Optional) If true, the assignment will be omitted from the student's final // grade "omit_from_final_grade": true, // (Optional) If true, the assignment will not be shown in any gradebooks "hide_in_gradebook": true, // Boolean indicating if the assignment is moderated. "moderated_grading": true, // The maximum number of provisional graders who may issue grades for this // assignment. Only relevant for moderated assignments. Must be a positive // value, and must be set to 1 if the course has fewer than two active // instructors. Otherwise, the maximum value is the number of active instructors // in the course minus one, or 10 if the course has more than 11 active // instructors. "grader_count": 3, // The user ID of the grader responsible for choosing final grades for this // assignment. Only relevant for moderated assignments. "final_grader_id": 3, // Boolean indicating if provisional graders' comments are visible to other // provisional graders. Only relevant for moderated assignments. "grader_comments_visible_to_graders": true, // Boolean indicating if provisional graders' identities are hidden from other // provisional graders. Only relevant for moderated assignments with // grader_comments_visible_to_graders set to true. "graders_anonymous_to_graders": true, // Boolean indicating if provisional grader identities are visible to the final // grader. Only relevant for moderated assignments. "grader_names_visible_to_final_grader": true, // Boolean indicating if the assignment is graded anonymously. If true, graders // cannot see student identities. "anonymous_grading": true, // The number of submission attempts a student can make for this assignment. -1 // is considered unlimited. "allowed_attempts": 2, // Whether the assignment has manual posting enabled. Only relevant for courses // using New Gradebook. "post_manually": true, // (Optional) If 'score_statistics' and 'submission' are included in the // 'include' parameter and statistics are available, includes the min, max, and // mode for this assignment "score_statistics": null, // (Optional) If retrieving a single assignment and 'can_submit' is included in // the 'include' parameter, flags whether user has the right to submit the // assignment (i.e. checks enrollment dates, submission types, locked status, // attempts remaining, etc...). Including 'can submit' automatically includes // 'submission' in the include parameter. Not available when observed_users are // included. "can_submit": true, // (Optional) The academic benchmark(s) associated with the assignment or the // assignment's rubric. Only included if 'ab_guid' is included in the 'include' // parameter. "ab_guid": ["ABCD", "EFGH"], // (Optional) The account-level academic integrity pledge text a student must // accept before submitting this assignment. Only present if // 'academic_integrity_pledge' is included in the 'include' parameter AND the // pledge is enabled for the account; otherwise the key is omitted. When present // but the pledge does not apply to this particular assignment (e.g. external // tool assignments or Canvas Career courses), the value is null. "academic_integrity_pledge": "This submission reflects my own ideas and work", // The id of the attachment to be annotated by students. Relevant only if // submission_types includes 'student_annotation'. "annotatable_attachment_id": null, // (Optional) Boolean indicating whether student names are anonymized "anonymize_students": false, // (Optional) Boolean indicating whether the Respondus LockDown Browser® is // required for this assignment. "require_lockdown_browser": false, // (Optional) Boolean indicating whether this assignment has important dates. "important_dates": false, // (Optional, Deprecated) Boolean indicating whether notifications are muted for // this assignment. "muted": false, // Boolean indicating whether peer reviews are anonymous. "anonymous_peer_reviews": false, // Boolean indicating whether instructor anotations are anonymous. "anonymous_instructor_annotations": false, // Boolean indicating whether this assignment has graded submissions. "graded_submissions_exist": false, // Boolean indicating whether this is a quiz lti assignment. "is_quiz_assignment": false, // Boolean indicating whether this assignment is in a closed grading period. "in_closed_grading_period": false, // Boolean indicating whether this assignment can be duplicated. "can_duplicate": false, // If this assignment is a duplicate, it is the original assignment's course_id "original_course_id": 4, // If this assignment is a duplicate, it is the original assignment's id "original_assignment_id": 4, // If this assignment is a duplicate, it is the original assignment's // lti_resource_link_id "original_lti_resource_link_id": 4, // If this assignment is a duplicate, it is the original assignment's name "original_assignment_name": "some assignment", // If this assignment is a duplicate, it is the original assignment's quiz_id "original_quiz_id": 4, // String indicating what state this assignment is in. "workflow_state": "unpublished" } ``` #### A BasicUser object looks like: ```js { // The user's ID "id": "123456", // The user's name "name": "Dankey Kang" } ``` #### An AssignmentOverride object looks like: ```js { // the ID of the assignment override "id": 4, // the ID of the assignment the override applies to (present if the override // applies to an assignment) "assignment_id": 123, // the ID of the quiz the override applies to (present if the override applies // to a quiz) "quiz_id": 123, // the ID of the module the override applies to (present if the override applies // to a module) "context_module_id": 123, // the ID of the discussion the override applies to (present if the override // applies to an ungraded discussion) "discussion_topic_id": 123, // the ID of the page the override applies to (present if the override applies // to a page) "wiki_page_id": 123, // the ID of the file the override applies to (present if the override applies // to a file) "attachment_id": 123, // the IDs of the override's target students (present if the override targets an // ad-hoc set of students) "student_ids": [1, 2, 3], // the ID of the override's target group (present if the override targets a // group and the assignment is a group assignment) "group_id": 2, // the ID of the overrides's target section (present if the override targets a // section) "course_section_id": 1, // the title of the override "title": "an assignment override", // the overridden due at (present if due_at is overridden) "due_at": "2012-07-01T23:59:00-06:00", // the overridden all day flag (present if due_at is overridden) "all_day": true, // the overridden all day date (present if due_at is overridden) "all_day_date": "2012-07-01", // the overridden unlock at (present if unlock_at is overridden) "unlock_at": "2012-07-01T23:59:00-06:00", // the overridden lock at, if any (present if lock_at is overridden) "lock_at": "2012-07-01T23:59:00-06:00" } ``` ## [Delete an assignment](#method.assignments.destroy) [AssignmentsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_controller.rb) #### `DELETE /api/v1/courses/:course_id/assignments/:id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/assignments/:id` Delete the given assignment. #### Example Request: ```bash curl https:///api/v1/courses//assignments/ \ -X DELETE \ -H 'Authorization: Bearer ' ``` Returns an [Assignment](#assignment) object. ## [List assignments](#method.assignments_api.index) [AssignmentsApiController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `GET /api/v1/courses/:course_id/assignments` **Scope:** `url:GET|/api/v1/courses/:course_id/assignments` #### `GET /api/v1/courses/:course_id/assignment_groups/:assignment_group_id/assignments` **Scope:** `url:GET|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id/assignments` Returns the paginated list of assignments for the current course or assignment group. #### Request Parameters: | Parameter | Type | Description | | -------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Optional information to include with each assignment:submission:: The current user's current +Submission+assignment\_visibility:: An array of ids of students who can see the assignmentall\_dates:: An array of +AssignmentDate+ structures, one for each override, and also a +base+ if the assignment has an "Everyone" / "Everyone Else" dateoverrides:: An array of +AssignmentOverride+ structuresobserved\_users:: An array of submissions for observed userscan\_edit:: an extra Boolean value will be included with each +Assignment+ (and +AssignmentDate+ if +all\_dates+ is supplied) to indicate whether the caller can edit the assignment or date. Moderated grading and closed grading periods may restrict a user's ability to edit an assignment.score\_statistics:: An object containing min, max, and mean score on this assignment. This will not be included for students if there are less than 5 graded assignments or if disabled by the instructor. Only valid if 'submission' is also included.ab\_guid:: An array of guid strings for academic benchmarks Allowed values: submission, assignment\_visibility, all\_dates, overrides, observed\_users, can\_edit, score\_statistics, ab\_guid | | `search_term` | `string` | The partial title of the assignments to match and return. | | `override_assignment_dates` | `boolean` | Apply assignment overrides for each assignment, defaults to true. | | `needs_grading_count_by_section` | `boolean` | Split up "needs\_grading\_count" by sections into the "needs\_grading\_count\_by\_section" key, defaults to false | | `bucket` | `string` | If included, only return certain assignments depending on due date and submission status. Allowed values: `past`, `overdue`, `undated`, `ungraded`, `unsubmitted`, `upcoming`, `future` | | `assignment_ids[]` | `string` | if set, return only assignments specified | | `order_by` | `string` | Determines the order of the assignments. Defaults to "position". Allowed values: `position`, `name`, `due_at` | | `post_to_sis` | `boolean` | Return only assignments that have post\_to\_sis set or not set. | | `new_quizzes` | `boolean` | Return only New Quizzes assignments | Returns a list of [Assignment](#assignment) objects. ## [List assignments for user](#method.assignments_api.user_index) [AssignmentsApiController#user\_index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `GET /api/v1/users/:user_id/courses/:course_id/assignments` **Scope:** `url:GET|/api/v1/users/:user_id/courses/:course_id/assignments` Returns the paginated list of assignments for the specified user if the current user has rights to view. See [List assignments](#method.assignments_api.index) for valid arguments. ## [Duplicate assignment](#method.assignments_api.duplicate) [AssignmentsApiController#duplicate](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `POST /api/v1/courses/:course_id/assignments/:assignment_id/duplicate` **Scope:** `url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/duplicate` Duplicate an assignment and return a json based on result\_type argument. #### Request Parameters: | Parameter | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `result_type` | `string` | Optional information:When the root account has the feature newquizzes\_on\_quiz\_page enabledand this argument is set to "Quiz" the response will be serialized into aquiz format;When this argument isn't specified the response will be serialized into anassignment format; Allowed values: Quiz | #### Example Request: ```bash curl -X POST -H 'Authorization: Bearer ' \ https:///api/v1/courses/123/assignments/123/duplicate ``` ```bash curl -X POST -H 'Authorization: Bearer ' \ https:///api/v1/courses/123/assignments/123/duplicate?result_type=Quiz ``` Returns an [Assignment](#assignment) object. ## [List group members for a student on an assignment](#method.assignments_api.student_group_members) [AssignmentsApiController#student\_group\_members](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `GET /api/v1/courses/:course_id/assignments/:assignment_id/users/:user_id/group_members` **Scope:** `url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/users/:user_id/group_members` Returns student ids and names for the group. #### Example Request: ```bash curl https:///api/v1/courses/1/assignments/1/users/1/group_members ``` Returns a list of [BasicUser](#basicuser) objects. ## [Get a single assignment](#method.assignments_api.show) [AssignmentsApiController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `GET /api/v1/courses/:course_id/assignments/:id` **Scope:** `url:GET|/api/v1/courses/:course_id/assignments/:id` Returns the assignment with the given id. #### Request Parameters: | Parameter | Type | Description | | -------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Associations to include with the assignment. The "assignment\_visibility" optionrequires that the Differentiated Assignments course feature be turned on. If"observed\_users" is passed, submissions for observed users will also be included.For "score\_statistics" to be included, the "submission" option must also be set.The "peer\_review" option returns peer review sub assignment data if it exists, regardlessof the Peer Review Allocation and Grading feature state. If no peer review sub assignmentexists, the feature must be enabled to receive a null value; otherwise the key is omitted.The "academic\_integrity\_pledge" option returns the account-level academic integritypledge text a student must accept before submitting this assignment. The key is onlypresent when the pledge is enabled for the account; when present but the pledge does notapply to this assignment (e.g. external tool assignments or Canvas Career courses) thevalue is null. Allowed values: submission, assignment\_visibility, overrides, observed\_users, can\_edit, score\_statistics, ab\_guid, peer\_review, academic\_integrity\_pledge | | `override_assignment_dates` | `boolean` | Apply assignment overrides to the assignment, defaults to true. | | `needs_grading_count_by_section` | `boolean` | Split up "needs\_grading\_count" by sections into the "needs\_grading\_count\_by\_section" key, defaults to false | | `all_dates` | `boolean` | All dates associated with the assignment, if applicable | Returns an [Assignment](#assignment) object. ## [Create an assignment](#method.assignments_api.create) [AssignmentsApiController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `POST /api/v1/courses/:course_id/assignments` **Scope:** `url:POST|/api/v1/courses/:course_id/assignments` Create a new assignment for this course. The assignment is created in the active state. #### Request Parameters: | Parameter | Type | Description | | --------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `assignment[name]` | Required `string` | The assignment name. | | `assignment[position]` | `integer` | The position of this assignment in the group when displayingassignment lists. | | `assignment[submission_types][]` | `string` | List of supported submission types for the assignment.Unless the assignment is allowing online submissions, the array shouldonly have one element.If not allowing online submissions, your options are:"online\_quiz""none""on\_paper""discussion\_topic""external\_tool"If you are allowing online submissions, you can have one or manyallowed submission types:"online\_upload""online\_text\_entry""online\_url""media\_recording" (Only valid when the Kaltura plugin is enabled)"student\_annotation" Allowed values: online\_quiz, none, on\_paper, discussion\_topic, external\_tool, online\_upload, online\_text\_entry, online\_url, media\_recording, student\_annotation | | `assignment[allowed_extensions][]` | `string` | Allowed extensions if submission\_types includes "online\_upload"Example:allowed\_extensions: \["docx","ppt"] | | `assignment[turnitin_enabled]` | `boolean` | Only applies when the Turnitin plugin is enabled for a course andthe submission\_types array includes "online\_upload".Toggles Turnitin submissions for the assignment.Will be ignored if Turnitin is not available for the course. | | `assignment[vericite_enabled]` | `boolean` | Only applies when the VeriCite plugin is enabled for a course andthe submission\_types array includes "online\_upload".Toggles VeriCite submissions for the assignment.Will be ignored if VeriCite is not available for the course. | | `assignment[turnitin_settings]` | `string` | Settings to send along to turnitin. See Assignment object definition forformat. | | `assignment[integration_data]` | `string` | Data used for SIS integrations. Requires admin-level token with the "Manage SIS" permission. JSON string required. | | `assignment[integration_id]` | `string` | Unique ID from third party integrations | | `assignment[peer_reviews]` | `boolean` | If submission\_types does not include external\_tool,discussion\_topic,online\_quiz, or on\_paper, determines whether or not peer reviewswill be turned on for the assignment. | | `assignment[automatic_peer_reviews]` | `boolean` | Whether peer reviews will be assigned automatically by Canvas or ifteachers must manually assign peer reviews. Does not apply if peer reviewsare not enabled. | | `assignment[notify_of_update]` | `boolean` | If true, Canvas will send a notification to students in the classnotifying them that the content has changed. | | `assignment[group_category_id]` | `integer` | If present, the assignment will become a group assignment assignedto the group. | | `assignment[grade_group_students_individually]` | `integer` | If this is a group assignment, teachers have the options to gradestudents individually. If false, Canvas will apply the assignment'sscore to each member of the group. If true, the teacher can manuallyassign scores to each member of the group. | | `assignment[external_tool_tag_attributes]` | `string` | Hash of external tool parameters if submission\_types is \["external\_tool"].See Assignment object definition for format. | | `assignment[points_possible]` | `number` | The maximum points possible on the assignment. | | `assignment[grading_type]` | `string` | The strategy used for grading the assignment.The assignment defaults to "points" if this field is omitted. Allowed values: pass\_fail, percent, letter\_grade, gpa\_scale, points, not\_graded | | `assignment[due_at]` | `DateTime` | The day/time the assignment is due. Must be between the lock dates if there are lock dates.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[lock_at]` | `DateTime` | The day/time the assignment is locked after. Must be after the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[unlock_at]` | `DateTime` | The day/time the assignment is unlocked. Must be before the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[description]` | `string` | The assignment's description, supports HTML. | | `assignment[assignment_group_id]` | `integer` | The assignment group id to put the assignment in.Defaults to the top assignment group in the course. | | `assignment[assignment_overrides][]` | `AssignmentOverride` | List of overrides for the assignment. | | `assignment[only_visible_to_overrides]` | `boolean` | Whether this assignment is only visible to overrides(Only useful if 'differentiated assignments' account setting is on) | | `assignment[published]` | `boolean` | Whether this assignment is published.(Only useful if 'draft state' account setting is on)Unpublished assignments are not visible to students. | | `assignment[grading_standard_id]` | `integer` | The grading standard id to set for the course. If no value is provided for this argument the current grading\_standard will be un-set from this course.This will update the grading\_type for the course to 'letter\_grade' unless it is already 'gpa\_scale'. | | `assignment[omit_from_final_grade]` | `boolean` | Whether this assignment is counted towards a student's final grade. | | `assignment[hide_in_gradebook]` | `boolean` | Whether this assignment is shown in the gradebook. | | `assignment[quiz_lti]` | `boolean` | Whether this assignment should use the Quizzes 2 LTI tool. Sets thesubmission type to 'external\_tool' and configures the external toolattributes to use the Quizzes 2 LTI tool configured for this course.Has no effect if no Quizzes 2 LTI tool is configured. | | `assignment[moderated_grading]` | `boolean` | Whether this assignment is moderated. | | `assignment[grader_count]` | `integer` | The maximum number of provisional graders who may issue grades for thisassignment. Only relevant for moderated assignments. Must be a positivevalue, and must be set to 1 if the course has fewer than two activeinstructors. Otherwise, the maximum value is the number of activeinstructors in the course minus one, or 10 if the course has more than 11active instructors. | | `assignment[final_grader_id]` | `integer` | The user ID of the grader responsible for choosing final grades for thisassignment. Only relevant for moderated assignments. | | `assignment[grader_comments_visible_to_graders]` | `boolean` | Boolean indicating if provisional graders' comments are visible to otherprovisional graders. Only relevant for moderated assignments. | | `assignment[graders_anonymous_to_graders]` | `boolean` | Boolean indicating if provisional graders' identities are hidden fromother provisional graders. Only relevant for moderated assignments. | | `assignment[graders_names_visible_to_final_grader]` | `boolean` | Boolean indicating if provisional grader identities are visible to thethe final grader. Only relevant for moderated assignments. | | `assignment[anonymous_grading]` | `boolean` | Boolean indicating if the assignment is graded anonymously. If true,graders cannot see student identities. | | `assignment[allowed_attempts]` | `integer` | The number of submission attempts allowed for this assignment. Set to -1 for unlimited attempts. | | `assignment[annotatable_attachment_id]` | `integer` | The Attachment ID of the document being annotated.Only applies when submission\_types includes "student\_annotation". | | `assignment[asset_processors][]` | `Array` | Document processors for this assignment. New document processors can only be addedvia the interactive LTI Deep Linking flow (in a browser), not via API token or JWT authentication.Deletion of document processors (passing an empty array) is allowed via API. | | `assignment[peer_review][points_possible]` | `number` | The maximum points possible for peer reviews. | | `assignment[peer_review][grading_type]` | `string` | The strategy used for grading peer reviews.Defaults to "points" if this field is omitted. Allowed values: pass\_fail, percent, letter\_grade, gpa\_scale, points | | `assignment[peer_review][due_at]` | `DateTime` | The day/time the peer reviews are due. Must be between the lock dates if there are lock dates.Accepts times in ISO 8601 format, e.g. 2025-08-20T12:10:00Z. | | `assignment[peer_review][lock_at]` | `DateTime` | The day/time the peer reviews are locked after. Must be after the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2025-08-25T12:10:00Z. | | `assignment[peer_review][unlock_at]` | `DateTime` | The day/time the peer reviews are unlocked. Must be before the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2025-08-15T12:10:00Z. | | `assignment[peer_review][peer_review_overrides][]` | `AssignmentOverride` | List of overrides for the peer reviews. | Returns an [Assignment](#assignment) object. ## [Edit an assignment](#method.assignments_api.update) [AssignmentsApiController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `PUT /api/v1/courses/:course_id/assignments/:id` **Scope:** `url:PUT|/api/v1/courses/:course_id/assignments/:id` Modify an existing assignment. #### Request Parameters: | Parameter | Type | Description | | --------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `assignment[name]` | `string` | The assignment name. | | `assignment[position]` | `integer` | The position of this assignment in the group when displayingassignment lists. | | `assignment[submission_types][]` | `string` | Only applies if the assignment doesn't have student submissions.List of supported submission types for the assignment.Unless the assignment is allowing online submissions, the array shouldonly have one element.If not allowing online submissions, your options are:"online\_quiz""none""on\_paper""discussion\_topic""external\_tool"If you are allowing online submissions, you can have one or manyallowed submission types:"online\_upload""online\_text\_entry""online\_url""media\_recording" (Only valid when the Kaltura plugin is enabled)"student\_annotation" Allowed values: online\_quiz, none, on\_paper, discussion\_topic, external\_tool, online\_upload, online\_text\_entry, online\_url, media\_recording, student\_annotation | | `assignment[allowed_extensions][]` | `string` | Allowed extensions if submission\_types includes "online\_upload"Example:allowed\_extensions: \["docx","ppt"] | | `assignment[turnitin_enabled]` | `boolean` | Only applies when the Turnitin plugin is enabled for a course andthe submission\_types array includes "online\_upload".Toggles Turnitin submissions for the assignment.Will be ignored if Turnitin is not available for the course. | | `assignment[vericite_enabled]` | `boolean` | Only applies when the VeriCite plugin is enabled for a course andthe submission\_types array includes "online\_upload".Toggles VeriCite submissions for the assignment.Will be ignored if VeriCite is not available for the course. | | `assignment[turnitin_settings]` | `string` | Settings to send along to turnitin. See Assignment object definition forformat. | | `assignment[sis_assignment_id]` | `string` | The sis id of the Assignment | | `assignment[integration_data]` | `string` | Data used for SIS integrations. Requires admin-level token with the "Manage SIS" permission. JSON string required. | | `assignment[integration_id]` | `string` | Unique ID from third party integrations | | `assignment[peer_reviews]` | `boolean` | If submission\_types does not include external\_tool,discussion\_topic,online\_quiz, or on\_paper, determines whether or not peer reviewswill be turned on for the assignment. | | `assignment[automatic_peer_reviews]` | `boolean` | Whether peer reviews will be assigned automatically by Canvas or ifteachers must manually assign peer reviews. Does not apply if peer reviewsare not enabled. | | `assignment[notify_of_update]` | `boolean` | If true, Canvas will send a notification to students in the classnotifying them that the content has changed. | | `assignment[group_category_id]` | `integer` | If present, the assignment will become a group assignment assignedto the group. | | `assignment[grade_group_students_individually]` | `integer` | If this is a group assignment, teachers have the options to gradestudents individually. If false, Canvas will apply the assignment'sscore to each member of the group. If true, the teacher can manuallyassign scores to each member of the group. | | `assignment[external_tool_tag_attributes]` | `string` | Hash of external tool parameters if submission\_types is \["external\_tool"].See Assignment object definition for format. | | `assignment[points_possible]` | `number` | The maximum points possible on the assignment. | | `assignment[grading_type]` | `string` | The strategy used for grading the assignment.The assignment defaults to "points" if this field is omitted. Allowed values: pass\_fail, percent, letter\_grade, gpa\_scale, points, not\_graded | | `assignment[due_at]` | `DateTime` | The day/time the assignment is due.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[lock_at]` | `DateTime` | The day/time the assignment is locked after. Must be after the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[unlock_at]` | `DateTime` | The day/time the assignment is unlocked. Must be before the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[description]` | `string` | The assignment's description, supports HTML. | | `assignment[assignment_group_id]` | `integer` | The assignment group id to put the assignment in.Defaults to the top assignment group in the course. | | `assignment[assignment_overrides][]` | `AssignmentOverride` | List of overrides for the assignment.If the +assignment\[assignment\_overrides]+ key is absent, any existingoverrides are kept as is. If the +assignment\[assignment\_overrides]+ key ispresent, existing overrides are updated or deleted (and new ones created,as necessary) to match the provided list. | | `assignment[only_visible_to_overrides]` | `boolean` | Whether this assignment is only visible to overrides(Only useful if 'differentiated assignments' account setting is on) | | `assignment[published]` | `boolean` | Whether this assignment is published.(Only useful if 'draft state' account setting is on)Unpublished assignments are not visible to students. | | `assignment[grading_standard_id]` | `integer` | The grading standard id to set for the course. If no value is provided for this argument the current grading\_standard will be un-set from this course.This will update the grading\_type for the course to 'letter\_grade' unless it is already 'gpa\_scale'. | | `assignment[omit_from_final_grade]` | `boolean` | Whether this assignment is counted towards a student's final grade. | | `assignment[hide_in_gradebook]` | `boolean` | Whether this assignment is shown in the gradebook. | | `assignment[moderated_grading]` | `boolean` | Whether this assignment is moderated. | | `assignment[grader_count]` | `integer` | The maximum number of provisional graders who may issue grades for thisassignment. Only relevant for moderated assignments. Must be a positivevalue, and must be set to 1 if the course has fewer than two activeinstructors. Otherwise, the maximum value is the number of activeinstructors in the course minus one, or 10 if the course has more than 11active instructors. | | `assignment[final_grader_id]` | `integer` | The user ID of the grader responsible for choosing final grades for thisassignment. Only relevant for moderated assignments. | | `assignment[grader_comments_visible_to_graders]` | `boolean` | Boolean indicating if provisional graders' comments are visible to otherprovisional graders. Only relevant for moderated assignments. | | `assignment[graders_anonymous_to_graders]` | `boolean` | Boolean indicating if provisional graders' identities are hidden fromother provisional graders. Only relevant for moderated assignments. | | `assignment[graders_names_visible_to_final_grader]` | `boolean` | Boolean indicating if provisional grader identities are visible to thethe final grader. Only relevant for moderated assignments. | | `assignment[anonymous_grading]` | `boolean` | Boolean indicating if the assignment is graded anonymously. If true,graders cannot see student identities. | | `assignment[allowed_attempts]` | `integer` | The number of submission attempts allowed for this assignment. Set to -1 or null forunlimited attempts. | | `assignment[annotatable_attachment_id]` | `integer` | The Attachment ID of the document being annotated.Only applies when submission\_types includes "student\_annotation". | | `assignment[asset_processors][]` | `Array` | Document processors for this assignment. New document processors can only be addedvia the interactive LTI Deep Linking flow (in a browser), not via API token or JWT authentication.Deletion of document processors (passing an empty array) is allowed via API. | | `assignment[force_updated_at]` | `boolean` | If true, updated\_at will be set even if no changes were made. | | `assignment[peer_review][points_possible]` | `number` | The maximum points possible for peer reviews. | | `assignment[peer_review][grading_type]` | `string` | The strategy used for grading peer reviews.Defaults to "points" if this field is omitted. Allowed values: pass\_fail, percent, letter\_grade, gpa\_scale, points | | `assignment[peer_review][due_at]` | `DateTime` | The day/time the peer reviews are due. Must be between the lock dates if there are lock dates.Accepts times in ISO 8601 format, e.g. 2025-08-20T12:10:00Z. | | `assignment[peer_review][lock_at]` | `DateTime` | The day/time the peer reviews are locked after. Must be after the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2025-08-25T12:10:00Z. | | `assignment[peer_review][unlock_at]` | `DateTime` | The day/time the peer reviews are unlocked. Must be before the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2025-08-15T12:10:00Z. | | `assignment[peer_review][peer_review_overrides][]` | `AssignmentOverride` | List of overrides for the peer reviews.When updating overrides:- Include "id" to update an existing override- Omit "id" to create a new override- Omit an override from the list to delete it | | `assignment[submission_types][]` | `string` | **\[DEPRECATED]** Effective 2021-05-26 (notice given 2021-02-18) Only applies if the assignment doesn't have student submissions. | Returns an [Assignment](#assignment) object. ## [Bulk update assignment dates](#method.assignments_api.bulk_update) [AssignmentsApiController#bulk\_update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `PUT /api/v1/courses/:course_id/assignments/bulk_update` **Scope:** `url:PUT|/api/v1/courses/:course_id/assignments/bulk_update` Update due dates and availability dates for multiple assignments in a course. Accepts a JSON array of objects containing two keys each: +id+, the assignment id, and +all\_dates+, an array of +AssignmentDate+ structures containing the base and/or override dates for the assignment, as returned from the [List assignments](#method.assignments_api.index) endpoint with +include\[]=all\_dates+. This endpoint cannot create or destroy assignment overrides; any existing assignment overrides that are not referenced in the arguments will be left alone. If an override is given, any dates that are not supplied with it will be defaulted. To clear a date, specify null explicitly. All referenced assignments will be validated before any are saved. A list of errors will be returned if any provided dates are invalid, and no changes will be saved. The bulk update is performed in a background job, use the [Progress API](https://developerdocs.instructure.com/services/canvas/resources/pages/3xnEhMZQuJstdXB8KHiv#method.progress.show) to check its status. #### Example Request: ```bash curl 'https:///api/v1/courses/1/assignments/bulk_update' \ -X PUT \ --data '[{ "id": 1, "all_dates": [{ "base": true, "due_at": "2020-08-29T23:59:00-06:00" }, { "id": 2, "due_at": "2020-08-30T23:59:00-06:00" }] }]' \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " ``` Returns a [Progress](/services/canvas/resources/progress#progress) object. ## [List assignment overrides](#method.assignment_overrides.index)
` somewhere in the query string. The app can then extract the code, and use it along with the client\_id and client\_secret to obtain the final access\_key. #### [Step 3: Exchange the code for the final access token](#oauth2-flow-3) [Back to Top](#top) To get a new access token and refresh token, send a [POST request to login/oauth2/token](/services/canvas/oauth2/file.oauth_endpoints#post-login-oauth2-token) with the following parameters: **Parameters** | Parameter | Value | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | grant\_type | authorization\_code | | client\_id | Your client\_id | | client\_secret | Your client\_secret | | redirect\_uri | If a redirect\_uri was passed to the initial request in step 1, the same redirect\_uri must be given here. | | code | code from canvas | | replace\_tokens | (optional) If this option is set to \`1\`, existing access tokens issued for this developer key/secret will be destroyed and replaced with the new token that is returned from this request | Note that the once the code issued in step 2 is used in a POST request to this endpoint, it is invalidated and further requests for tokens with the same code will fail. ### [Using an Access Token to authenticate requests](#using-access-tokens) [Back to Top](#top) Once you have an OAuth access token, you can use it to make API requests. If possible, using the HTTP Authorization header is recommended. OAuth2 Token sent in header: ```bash curl -H "Authorization: Bearer " "https://canvas.instructure.com/api/v1/courses" ``` Sending the access token in the query string or POST parameters is also supported, but discouraged as it increases the chances of the token being logged or leaked in transit. OAuth2 Token sent in query string: ```bash curl "https://canvas.instructure.com/api/v1/courses?access_token=" ``` ### [Using a Refresh Token to get a new Access Token](#using-refresh-tokens) [Back to Top](#top) Access tokens have a 1 hour lifespan. When the refresh flow is taken, Canvas will update the access token to a new value, reset the expiration timer, and return the new access token as part of the response. When refreshing tokens the user will not be asked to authorize the application again. To refresh the access token, send a [POST request to login/oauth2/token](/services/canvas/oauth2/file.oauth_endpoints#post-login-oauth2-token) with the following parameters: **Parameters** | Parameter | Value | | -------------- | ------------------------------------------------- | | grant\_type | refresh\_token | | client\_id | Your client\_id | | client\_secret | Your client\_secret | | refresh\_token | refresh\_token from initial access\_token request | The response to this request will not contain a new refresh token; the same refresh token is to be reused. ### [Logging Out](/services/canvas/oauth2/file.oauth_endpoints#delete-login-oauth2-token) [Back to Top](#top) To logout, simply send a [DELETE request to login/oauth2/token](/services/canvas/oauth2/file.oauth_endpoints#delete-login-oauth2-token) ## [Accessing LTI Advantage Services](#accessing-lti-advantage-services) [Back to Top](#top) LTI Advantage services, such as [Names and Role Provisioning Services](https://www.imsglobal.org/spec/lti-nrps/v2p0) and [Assignment and Grade Services](https://www.imsglobal.org/spec/lti-ags/v2p0/), require use of a client credentials grant flow for request authentication. This workflow is best summarized on the IMS Security Framework (specifically [Section 4](https://www.imsglobal.org/spec/security/v1p0/#using-oauth-2-0-client-credentials-grant)). Our goal here is to highlight some nuances that might help you access these services in Canvas, rather than describing the specification in detail. ### [Step 1: Developer Key Setup](#developer-key-setup) [Back to Top](#top) Before the client\_credentials grant flow can be achieved, an [LTI developer key must be created](https://community.canvaslms.com/t5/Admin-Guide/How-do-I-configure-an-LTI-key-for-an-account/ta-p/140). During developer key configuration, a public JWK can either be configured statically or can be dynamically rotated by providing JWKs by a URL that Canvas can reach. Tools may also use a previously issued client\_credentials token to [retroactively rotate the public JWK via an API request](/services/canvas/resources/public_jwk). The JWK must include an alg and use. **Example JWK** ``` "public_jwk": { "kty":"RSA", "alg":"RS256", "e":"AQAB", "kid":"8f796179-7ac4-48a3-a202-fc4f3d814fcd", "n":"nZA7QWcIwj-3N_RZ1qJjX6CdibU87y2l02yMay4KunambalP9g0fU9yILwLX9WYJINcXZDUf6QeZ-SSbblET-h8Q4OvfSQ7iuu0WqcvBGy8M0qoZ7I-NiChw8dyybMJHgpiP_AyxpCQnp3bQ6829kb3fopbb4cAkOilwVRBYPhRLboXma0cwcllJHPLvMp1oGa7Ad8osmmJhXhN9qdFFASg_OCQdPnYVzp8gOFeOGwlXfSFEgt5vgeU25E-ycUOREcnP7BnMUk7wpwYqlE537LWGOV5z_1Dqcqc9LmN-z4HmNV7b23QZW4_mzKIOY4IqjmnUGgLU9ycFj5YGDCts7Q", "use":"sig" } ``` ### [Step 2: Request an access token](#request-access-token) [Back to Top](#top) Once the developer key is configured and turned on, your tool can [request an LTI access token using the client\_credentials grant](/services/canvas/oauth2/file.oauth_endpoints#post-login-oauth2-token). This request must be signed by an RSA256 private key with a public key that is configured on the developer key as described in [Step 1: Developer Key Setup](#developer-key-setup). ### [Step 3: Use the access token to access LTI services](#use-access-token) [Back to Top](#top) Once you have an access token, you can use it to make LTI service requests. The access token must be included as a Bearer token in the Authorization header: ```bash curl -H "Authorization: Bearer " "https:///api/lti/courses/:course_id/names_and_roles" ``` Access tokens only work in the context of where a tool has been deployed. Tools can only access line items that are associated with their tool. The following endpoints are currently supported: #### Names and Role Provisioning Services * [Names and Role API](/services/canvas/resources/names_and_role) #### Assignment and Grade Services * [Line Items](/services/canvas/resources/line_items) * [Score](/services/canvas/resources/score) * [Result](/services/canvas/resources/result) *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # OAuth2 Endpoints {% hint style="warning" %} Developer keys issued after Oct 2015 generate tokens with a 1 hour expiration. Applications must use [refresh tokens](/services/canvas/oauth2/file.oauth#using-refresh-tokens) to generate new access tokens. {% endhint %} * [GET login/oauth2/auth](#get-login-oauth2-auth) * [POST login/oauth2/token](#post-login-oauth2-token) * [DELETE login/oauth2/token](#delete-login-oauth2-token) * [GET login/session\_token](#get-login-session-token) ## GET login/oauth2/auth ### GET https\://\/login/oauth2/auth?client\_id=XXX\&response\_type=code\&redirect\_uri=\%20\%20\ #### Parameters | Parameter | Required | Description | | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | client\_id | Required | The client id for your registered application. | | response\_type | Required | The type of OAuth2 response requested. The only currently supported value is `code`. | | redirect\_uri | Required | The URL where the user will be redirected after authorization. The domain of this URL must match the domain of the redirect\_uri stored on the developer key, or it must be a subdomain of that domain. For native applications, currently the only supported value is `urn:ietf:wg:oauth:2.0:oob`, signifying that the credentials will be retrieved out-of-band using an embedded browser or other functionality. | | state | Optional | Your application can pass Canvas an arbitrary piece of state in this parameter, which will be passed back to your application in Step 2. It's strongly encouraged that your application pass a unique identifier in the state parameter, and then verify in Step 2 that the state you receive back from Canvas is the same expected value. Failing to do this opens your application to the possibility of logging the wrong person in, as [described here](http://homakov.blogspot.com/2012/07/saferweb-most-common-oauth2.html). | | scope | Optional | This can be used to specify what information the Canvas API access token will provide access to. Canvas API scopes may be found beneath their corresponding endpoints in the "resources" documentation pages. If the developer key does not require scopes and no scope parameter is specified, the access token will have access to all scopes. If the developer key does require scopes and no scope parameter is specified, Canvas will respond with "invalid\_scope." To successfully pass multiple scope values, the scope parameter is included once, with multiple values separated by spaces. Passing multiple scope parameters, as is common in other areas of Canvas, causes only the last value to be applied to the generated token. | | purpose | Optional | This can be used to help the user identify which instance of an application this token is for. For example, a mobile device application could provide the name of the device. | | force\_login | Optional | Set to '1' if you want to force the user to enter their credentials, even if they're already logged into Canvas. By default, if a user already has an active Canvas web session, they will not be asked to re-enter their credentials. | | unique\_id | Optional | Set to the user's username to be populated in the login form in the event that the user must authenticate. | | prompt | Optional | If set to `none`, Canvas will immediately redirect to the `redirect_uri`. If the caller has a valid session with a "remember me" token or a token from a trusted Developer Key, the redirect will contain a `code=XYZ` param. If the caller has no session, the redirect will contain an `error=login_required` param. If the caller has a session, but no "remember me" or trusted token, the redirect will contain an `error=interaction_required` param. | ## POST login/oauth2/token See [Section 4.1.3](http://tools.ietf.org/html/rfc6749#section-4.1.3) of the OAuth2 RFC for more information about this process. ### POST /login/oauth2/token #### Parameters | Parameter | Required | Description | | ----------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | grant\_type | Required | Values currently supported: "authorization\_code", "refresh\_token", and "client\_credentials". | | client\_id | Required for grant\_types: authorization\_code, refresh\_token | The client id for your registered application. | | client\_secret | Required for grant\_types: authorization\_code, refresh\_token | The client secret for your registered application. | | redirect\_uri | Required for grant\_types: authorization\_code, refresh\_token | If a redirect\_uri was passed to the initial request in step 1, the same redirect\_uri must be given here. | | code | Required for grant\_type: authorization\_code | Required if grant\_type is authorization\_code. The code you received in a redirect response. | | refresh\_token | Required for grant\_type: refresh\_token | Required if grant\_type is refresh\_token. The refresh\_token you received in a redirect response. | | client\_assertion\_type | Required for grant\_type: client\_credentials | Currently the only supported value for this field is \`urn:ietf:params:oauth:client-assertion-type:jwt-bearer\`. | | client\_assertion | Required for grant\_type: client\_credentials | The signed jwt used to request an access token. Includes the value of Developer Key id as the sub claim of the jwt body. Should be signed by the private key of the stored public key on the DeveloperKey. | | scope | Required for grant\_type: client\_credentials | A list of scopes to be granted to the token. Currently only IMS defined scopes may be used. | #### Canvas API example responses For grant\_type of code or refresh\_token: | Parameter | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | access\_token | The OAuth2 Canvas API access token. | | token\_type | The type of token that is returned. | | user | A JSON object of canvas user id and user name. | | refresh\_token | The OAuth2 refresh token. | | expires\_in | Seconds until the access token expires. | | canvas\_region | For hosted Canvas, the AWS region (e.g. us-east-1) in which the institution that provided this token resides. For local or open source Canvas, this will have a value of "unknown". This field is safe to ignore. | When using grant\_type=code (ex: for Canvas API access): ``` { "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "token_type": "Bearer", "user": {"id":42, "name": "Jimi Hendrix"}, "refresh_token": "tIh2YBWGiC0GgGRglT9Ylwv2MnTvy8csfGyfK2PqZmkFYYqYZ0wui4tzI7uBwnN2", "expires_in": 3600, "canvas_region": "us-east-1" } ``` When using grant\_type=refresh\_token, the response will not contain a new refresh token since the same refresh token can be used multiple times: ``` { "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "token_type": "Bearer", "user": {"id":42, "name": "Jimi Hendrix"}, "expires_in": 3600 } ``` If scope=/auth/userinfo was specified in the [GET login/oauth2/auth](#get-login-oauth2-auth) request (ex: when using Canvas as an authentication service) then the response that results from [POST login/oauth2/token](#post-login-oauth2-token) would be: ``` { "access_token": null, "token_type": "Bearer", "user":{"id": 42, "name": "Jimi Hendrix"} } ``` #### Examples using client\_credentials When using grant\_type=client\_credentials (ex: [to access LTI Advantage Services](/services/canvas/oauth2/file.oauth#accessing-lti-advantage-services)): **Example request** This request must be signed by an RSA256 private key with a public key that is configured on the developer key as described in [Step 1: Developer Key Setup](/services/canvas/oauth2/file.oauth#developer-key-setup). ``` { "grant_type": "client_credentials", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "client_assertion": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjIwMTktMDYtMjFUMTQ6NTk6MzBaIn0.eyJpc3MiOiJodHRwczovL3d3dy5teS10b29sLmNvbSIsInN1YiI6Ilx1MDAzY2NsaWVudF9pZFx1MDAzZSIsImF1ZCI6Imh0dHA6Ly9cdTAwM2NjYW52YXNfZG9tYWluXHUwMDNlL2xvZ2luL29hdXRoMi90b2tlbiIsImlhdCI6MTU2MTc1MDAzMSwiZXhwIjoxNTYxNzUwNjMxLCJqdGkiOiJkZmZkYmRjZS1hOWYxLTQyN2ItOGZjYS02MDQxODIxOTg3ODMifQ.lUHCwDqx2ukKQ2vwoz_824IVcyq-rNdJKVpGUiJea5-Ybk_VfyKW5v0ky-4XTJrGHkDcj0T9J8qKfYbikqyetK44yXx1YGo-2Pn2GEZ26bZxCnuDUDhbqN8OZf4T8DnZsYP4OyhOseHERsHCzKF-SD2_Pk6ES5-Z8J55_aMyS3w3tl4nJtwsMm6FbMDp_FhSGE4xTwkBZ2KNM4JqkCwHGX_9KcpsPsHRFQjn9ysTeg-Qf7H2QFgFMFjsfQX-iSL_bQoC2npSz7rQ8awKMhCEYdMYZk2vVhQ7XQ8ysAyf3m1vlLbHjASpztcAB0lz_DJysT0Ep-Rh311Qf_vXHexjVA", "scope": "https://purl.imsglobal.org/spec/lti-ags/lineitem https://purl.imsglobal.org/spec/lti-ags/result/read" } ``` Below is an example of the decoded client\_assertion JWT in the above request: ``` //Header { "typ": "JWT", "alg": "RS256", "kid": "2019-06-21T14:59:30Z" } //Payload { "iss": "https://www.my-tool.com", "sub": "", "aud": "https:///login/oauth2/token", "iat": 1561750031, "exp": 1561750631, "jti": "dffdbdce-a9f1-427b-8fca-604182198783" } ``` NOTE: * the value of the sub claim should match the client\_id of the developer key in Canvas. * the value of the aud claim should contain either the domain of the Canvas account where the desired data resides, or the domain of the LTI 1.3 OIDC Auth endpoint, as described [here](/services/canvas/external-tools/lti/file.lti_launch_overview#step-2). * if the public key defined on the developer key is a JWK set (specified by an URL) the kid (key ID) value in the signed JWT header must match one of the public keys returned by the public key URL. **Example Response** | Parameter | Description | | ------------- | ------------------------------------------------------------------------- | | access\_token | The OAuth2 client\_credentials access token. | | token\_type | The type of token that is returned. | | expires\_in | Seconds until the access token expires. | | scope | The scope or space delimited list of scopes granted for the access token. | ``` { "access_token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ3d3cuZXhhbXBsZS5jb20iLCJpYXQiOiIxNDg1OTA3MjAwIiwiZXhwIjoiMTQ4NTkwNzUwMCIsImltc2dsb2JhbC5vcmcuc2VjdXJpdHkuc2NvcGUiOiJMdGlMaW5rU2V0dGluZ3MgU2NvcmUuaXRlbS5QVVQifQ.UWCuoD05KDYVQHEcciTV88YYtWWMwgb3sTbrjwxGBZA", "token_type" : "Bearer", "expires_in" : 3600, "scope" : "https://purl.imsglobal.org/spec/lti-ags/lineitem https://purl.imsglobal.org/spec/lti-ags/result/read" } ``` ## DELETE login/oauth2/token If your application supports logout functionality, you can revoke your own access token. This is useful for security reasons, as well as removing your application from the list of tokens on the user's profile page. Simply make an authenticated request to the following endpoint by including an Authorization header or providing the access\_token as a request parameter. ### DELETE /login/oauth2/token #### Parameters | Parameter | Required | Description | | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | expire\_sessions | Optional | Set this to '1' if you want to end all of the user's Canvas web sessions. Without this argument, the endpoint will leave web sessions intact.Additionally, if the user logged in to Canvas via a delegated authentication provider, and the provider supports Single Log Out functionality, the response will contain a forward\_url key. If you are still in control of the user's browsing session, it is recommended to then redirect them to this URL, in order to also log them out from where their session originated. Beware that it is unlikely that control will be returned to your application after this redirect. | #### Example responses ``` { "forward_url": "https://idp.school.edu/opaque_url" } ``` ## GET login/session\_token If your application needs to begin a normal web session in order to access features not supported via API (such as quiz taking), you can use your API access token in order to get a time-limited URL that can be fed to a browser or web view to begin a new web session. ### GET /login/session\_token #### Parameters | Parameter | Required | Description | | ---------- | -------- | ---------------------------------------------------------------------------------------------- | | return\_to | Optional | An optional URL to begin the web session at. Otherwise the user will be sent to the dashboard. | #### Example responses ``` { "session_url": "https://canvas.instructure.com/opaque_url" } ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Developer Keys Developer keys are OAuth2 client ID and secret pairs stored in Canvas that allow third-party applications to request access to Canvas API endpoints via the [OAuth2 flow](/services/canvas/oauth2/file.oauth). Access is granted after a user authorizes an app and Canvas creates an API access token that’s returned in the final request of the OAuth2 flow. Developer keys created in a root account, by root account administrators or Instructure employees, are only functional for the account they are created in and its sub-accounts. Developer keys created globally, by an Instructure employee, are functional in any Canvas account where they are enabled. By scoping the tokens, Canvas allows root account administrators to manage the specific API endpoints that tokens issued from a developer key have access to. ## Developer Key Scopes Developer key scopes allow root account administrators to restrict the tokens issued from developer keys to a subset of Canvas API endpoints in their account. Developer keys may be scoped or unscoped. Unscoped keys will have access to all Canvas resources available to the authorizing user. The following applies to scoped developer keys only: ### What are developer key scopes in Canvas? Each Canvas API endpoint has an associated scope. Canvas developer key scopes can only be enabled/disabled by a root account administrator or an Instructure employee. Scopes take the following form: ``` url:| ``` For example, the corresponding scope for the `GET /api/v1/courses/:course_id/rubrics` API endpoint would be ``` url:GET|/api/v1/courses/:course_id/rubrics ``` ### How do developer key scopes function? When requesting an access token, third-party applications should specify a `scope` parameter (see the [oauth endpoints documentation](/services/canvas/oauth2/file.oauth_endpoints#get-login-oauth2-auth)). The requested scopes must be a subset of the scopes set for the developer key. When a client makes any API request, Canvas will verify the requested endpoint's scope has been granted by the account administrator to the developer key of the request's access token. If the requested endpoint's scope has not been granted Canvas will respond with `401 Unauthorized`. ### Who can grant or revoke scopes for a developer key? For developer keys created in a specific root account, administrators for that account may grant or revoke scopes. When requesting a developer key, application owners should communicate with administrators which scopes their integrations require. For global developer keys, an Instructure employee may grant or revoke scopes. *Note:* If a scope is removed from a developer key, all access tokens derived from that key will be invalidated. In this case, clients should request a new access token. ### Where can I see what scopes are available? View the complete list of [token scopes](/services/canvas/resources/api_token_scopes). Scopes may also be found beneath their corresponding endpoints in the "resources" documentation pages. ### Configuring scopes on a developer key When creating or editing an API developer key, administrators can configure scopes in two ways: **Manual** - Browse and select scopes from a grouped list of all available Canvas API endpoints. **Paste Scopes** - Paste a list of scope strings directly into a text field. Scopes should be entered one per line or separated by spaces, using the format described above: ``` url:GET|/api/v1/courses/:course_id/rubrics url:POST|/api/v1/courses/:course_id/assignments ``` Any scope strings that are not recognized as valid Canvas API scopes will be flagged as invalid. The UI will display a warning listing the invalid scopes, and saving will be blocked until they are corrected or removed. ## Developer Key Management Developer key management features allow root account administrators to turn global developer keys "on" and "off" for only their account. ### What management features are available? Root account administrators may enable or disable global developer keys for their specific account. This means that vendors who wish to have integrations that work in any Canvas account may request a global developer key from Instructure allowing account administrators enable the key for their account. ### How do management features function? When a client uses the [OAuth2 Auth endpoint](/services/canvas/oauth2/file.oauth_endpoints#get-login-oauth2-auth) as part of the flow to retrieve an access token canvas will check the developer key associated with the `client_id`. If the developer key is not enabled in the requested account, Canvas will respond with `unauthorized_client`. When a client makes any API request, Canvas will check the developer key associated with the access token used in the request. If the developer key is not enabled for the requested account, Canvas will respond with `401 Unauthorized`. ## Other Considerations ### Maximum number of scopes When clients request an access token they may specify what scopes the token needs (see the [oauth endpoints documentation](/services/canvas/oauth2/file.oauth_endpoints#get-login-oauth2-auth)). Because the client sends the scopes they require in a GET request, the maximum number of scopes one access token can specify is limited by the maximum HTTP header size Canvas allows (8000 chars). On average, an access token may use up to 110 scopes. This number will vary depending on the actual length of the scopes used and any other headers sent in the [login oauth2 request](/services/canvas/oauth2/file.oauth_endpoints#get-login-oauth2-auth) along with the scopes. If the number of scopes required by the client exceeds this limitation, a second access token with the remaining scopes should be requested. ### Canvas API Includes Several Canvas APIs allow specifying an `include` parameter. This parameter allows nesting resources in JSON responses. For example, a request to the [assignment index endpoint](https://developerdocs.instructure.com/services/canvas/oauth2/pages/fmw03fjQMjjL5AFja2sQ#method.assignments_api.index) could be made to include the submission objects for each assignment. Responses to requests made with a scoped access token only support this functionality when the 'Allow Include Parameters' option is also enabled. When this option is disabled, a request is made with a scoped token Canvas will ignore `include` and `includes` parameters. ### Developer Key Scope Changes During the lifetime of a developer key, scopes may be added or removed by account administrators. Below is a description of possible changes and how each will affect access tokens: #### New scopes are added to a developer key Access tokens issued prior to the addition of the new scope will continue to function. These access tokens will not, however, be usable with the new scope. To access the newly added resources clients should request a new access token with scopes. The requested scopes must be a subset of the scopes on the developer key. #### Scopes are removed from a developer key Access tokens issued prior to the removal of the scope(s) will *not* continue to function. Clients should request a new access token with scopes. The requested scopes must be a subset of the scopes on the developer key. #### An unscoped developer key becomes scoped Access tokens issued prior to the change will *not* continue to function. Clients should request a new access token with scopes. The requested scopes must be a subset of the scopes on the developer key. If the client attempts to request a new access token without specifying scopes Canvas will respond with an error. For details on unscoped vs scoped developer key see `Developer Key Scopes` above. #### A scoped developer key becomes unscoped Access tokens issued prior to the change will continue to function *and* have access to all resources of the authorizing user. Clients may continue to request scoped access tokens, but these tokens will be functional for all resources available to the authorizing user. For details on unscoped vs scoped developer key see `Developer Key Scopes` above. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Resources # Access Tokens #### A Token object looks like: ```js { // The internal database ID of the token. "id": null, // The time the token was created. "created_at": null, // The time the token will permanently expire, or null if it does not // permanently expire. "expires_at": null, // The current state of the token. One of 'active', 'pending', 'disabled', or // 'deleted'. "workflow_state": null, // Whether the token should be remembered across sessions. Only applicable for // OAuth tokens. "remember_access": null, // The scopes associated with the token. If empty, there are no scope // limitations. "scopes": null, // If the token was created while masquerading, this is the ID of the real user. // Otherwise, null. "real_user_id": null, // The actual access token. Only included when the token is first created. "token": null, // A short, unique string that can be used to look up the token. "token_hint": null, // The ID of the user the token belongs to. "user_id": null, // The purpose of the token. "purpose": null, // If the token was created by an OAuth application, this is the name of that // application. Otherwise, null. "app_name": null, // Whether the current user can manually regenerate this token. "can_manually_regenerate": null } ``` ## [List access tokens for a user](#method.tokens.user_generated_tokens) [TokensController#user\_generated\_tokens](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `GET /api/v1/users/:user_id/user_generated_tokens` **Scope:** `url:GET|/api/v1/users/:user_id/user_generated_tokens` Returns a list of manually generated access tokens for the specified user. Note that the actual token values are only returned when the token is first created. #### Request Parameters: | Parameter | Type | Description | | ---------- | --------- | ------------------------------------------------------------------------- | | `per_page` | `integer` | The number of results to return per page. Defaults to 10. Maximum of 100. | Returns a list of [Token](#token) objects. ## [Show an access token](#method.tokens.show) [TokensController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `GET /api/v1/users/:user_id/tokens/:id` **Scope:** `url:GET|/api/v1/users/:user_id/tokens/:id` The ID can be the actual database ID of the token, or the 'token\_hint' value. ## [Create an access token](#method.tokens.create) [TokensController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `POST /api/v1/users/:user_id/tokens` **Scope:** `url:POST|/api/v1/users/:user_id/tokens` Create a new access token for the specified user. If the user is not the current user, the token will be created as "pending", and must be activated by the user before it can be used. #### Request Parameters: | Parameter | Type | Description | | ------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `token[purpose]` | Required `string` | The purpose of the token. | | `token[expires_at]` | `DateTime` | The time at which the token will expire. | | `token[scopes][]` | `Array` | The scopes to associate with the token.Ignored if the default developer key does not have the "enable scopes" option enabled.In such cases, the token will inherit the user's permissions instead. | ## [Update an access token](#method.tokens.update) [TokensController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `PUT /api/v1/users/:user_id/tokens/:id` **Scope:** `url:PUT|/api/v1/users/:user_id/tokens/:id` Update an existing access token. The ID can be the actual database ID of the token, or the 'token\_hint' value. Regenerating an expired token requires a new expiration date. #### Request Parameters: | Parameter | Type | Description | | ------------------- | ---------- | ---------------------------------------- | | `token[purpose]` | `string` | The purpose of the token. | | `token[expires_at]` | `DateTime` | The time at which the token will expire. | | `token[scopes][]` | `Array` | The scopes to associate with the token. | | `token[regenerate]` | `boolean` | Regenerate the actual token. | ## [Delete an access token](#method.tokens.destroy) [TokensController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/tokens_controller.rb) #### `DELETE /api/v1/users/:user_id/tokens/:id` **Scope:** `url:DELETE|/api/v1/users/:user_id/tokens/:id` The ID can be the actual database ID of the token, or the 'token\_hint' value. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Accessibility Course Scans ## [Trigger accessibility course scan](#method.accessibility_course_scans.create) [AccessibilityCourseScansController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accessibility_course_scans_controller.rb) #### `POST /api/v1/users/:user_id/educator_accessibility_course_scan` **Scope:** `url:POST|/api/v1/users/:user_id/educator_accessibility_course_scan` Queues a background job that scans all a11y-enabled courses where the user has an active teacher or designer enrollment. Idempotent — if a scan is already queued or running, the existing Progress is returned. Requires the educator\_dashboard feature flag on the root account and a11y\_checker\_account\_statistics on site admin. #### Request Parameters: | Parameter | Type | Description | | --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | | `user_id` | Required `string` | The ID of the user, or "self" for the current user.The requesting user may only trigger a scan for themselves. | Returns a [Progress](/services/canvas/resources/progress#progress) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Accessibility Course Statistics #### An AccessibilityCourseStatistic object looks like: ```js // Per-course accessibility issue counts for a user's active teacher/designer // courses. { // The ID of the accessibility course statistic record "id": 1, // The ID of the course "course_id": 42, // The name of the course "course_name": "Introduction to Biology", // The course code (short name) of the course "course_code": "BIO101", // Whether the course is published "published": true, // The number of active accessibility issues in the course "active_issue_count": 5, // The number of resolved accessibility issues in the course "resolved_issue_count": 3, // The number of closed accessibility issues in the course "closed_issue_count": 2, // The workflow state of the statistic record "workflow_state": "active", // The date and time the record was created "created_at": "2026-01-01T00:00:00Z", // The date and time the record was last updated "updated_at": "2026-01-02T00:00:00Z" } ``` ## [List accessibility course statistics](#method.accessibility_course_statistics.index) [AccessibilityCourseStatisticsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accessibility_course_statistics_controller.rb) #### `GET /api/v1/users/:user_id/educator_accessibility_course_statistics` **Scope:** `url:GET|/api/v1/users/:user_id/educator_accessibility_course_statistics` Returns per-course accessibility issue statistics for the current user's active teacher and designer courses. Only courses where the accessibility checker is enabled and whose workflow state is neither completed nor deleted are included. Only statistic records with workflow\_state "active" are returned. Requires the educator\_dashboard feature flag to be enabled on the root account, and a11y\_checker\_account\_statistics on site admin plus a11y\_checker on the account (i.e. a11y\_checker\_account\_statistics? must be true). #### Request Parameters: | Parameter | Type | Description | | -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | Required `string` | The ID of the user, or "self" for the current user.The requesting user may only retrieve their own statistics. | | `enrollment_term_id` | `string` | When present, only include courses that belong to the given enrollmentterm(s). Accepts a single term id or an array(enrollment\_term\_id\[]=1\&enrollment\_term\_id\[]=2), and each value may be aterm id or SIS term id. Returns 404 if any given term does not exist inthis account. | Returns a list of [AccessibilityCourseStatistic](#accessibilitycoursestatistic) objects. ## [List accessibility course statistic terms](#method.accessibility_course_statistics.terms) [AccessibilityCourseStatisticsController#terms](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accessibility_course_statistics_controller.rb) #### `GET /api/v1/users/:user_id/educator_accessibility_course_terms` **Scope:** `url:GET|/api/v1/users/:user_id/educator_accessibility_course_terms` Returns the distinct enrollment terms that the current user's active teacher and designer courses belong to -- the same courses reported by the List accessibility course statistics endpoint. Use this to populate a term filter for that endpoint. There is no "all terms" entry; "all terms" is represented by omitting the enrollment\_term\_id filter. Requires the same account settings and feature flags as the statistics endpoint. #### Request Parameters: | Parameter | Type | Description | | --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- | | `user_id` | Required `string` | The ID of the user, or "self" for the current user.The requesting user may only retrieve their own terms. | Returns a list of [EnrollmentTerm](/services/canvas/resources/enrollment_terms#enrollmentterm) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Account Calendars API for viewing and toggling settings of account calendars. An account calendar is available for each account in Canvas. All account calendars are hidden by default, but administrators with the `manage_account_calendar_visibility` permission may set calendars as visible. Administrators with the `manage_account_calendar_events` permission can create events in visible account calendars, and users associated with an account can add the calendar and see its events (if the calendar is visible). Events on calendars set as `auto_subscribe` calendars will appear on users' calendars even if they do not manually add it. #### An AccountCalendar object looks like: ```js { // the ID of the account associated with this calendar "id": 204, // the name of the account associated with this calendar "name": "Department of Chemistry", // the account's parent ID, or null if this is the root account "parent_account_id": 1, // the ID of the root account, or null if this is the root account "root_account_id": 1, // whether this calendar is visible to users "visible": true, // whether users see this calendar's events without needing to manually add it "auto_subscribe": false, // number of this account's direct sub-accounts "sub_account_count": 0, // Asset string of the account "asset_string": "account_4", // Object type "type": "account", // url to get full detailed events "calendar_event_url": "/accounts/2/calendar_events/%7B%7B%20id%20%7D%7D", // whether the user can create calendar events "can_create_calendar_events": true, // API path to create events for the account "create_calendar_event_url": "/accounts/2/calendar_events", // url to open the more options event editor "new_calendar_event_url": "/accounts/6/calendar_events/new" } ``` ## [List available account calendars](#method.account_calendars_api.index) [AccountCalendarsApiController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `GET /api/v1/account_calendars` **Scope:** `url:GET|/api/v1/account_calendars` Returns a paginated list of account calendars available to the current user. Includes visible account calendars where the user has an account association. #### Request Parameters: | Parameter | Type | Description | | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `search_term` | `string` | When included, searches available account calendars for the term. Returns matchingresults. Term must be at least 2 characters. | #### Example Request: ```bash curl https:///api/v1/account_calendars \ -H 'Authorization: Bearer ' ``` Returns a list of [AccountCalendar](#accountcalendar) objects. ## [Get a single account calendar](#method.account_calendars_api.show) [AccountCalendarsApiController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `GET /api/v1/account_calendars/:account_id` **Scope:** `url:GET|/api/v1/account_calendars/:account_id` Get details about a specific account calendar. #### Example Request: ```bash curl https:///api/v1/account_calendars/204 \ -H 'Authorization: Bearer ' ``` Returns an [AccountCalendar](#accountcalendar) object. ## [Update a calendar](#method.account_calendars_api.update) [AccountCalendarsApiController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `PUT /api/v1/account_calendars/:account_id` **Scope:** `url:PUT|/api/v1/account_calendars/:account_id` Set an account calendar's visibility and auto\_subscribe values. Requires the `manage_account_calendar_visibility` permission on the account. #### Request Parameters: | Parameter | Type | Description | | ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `visible` | `boolean` | Allow administrators with manage\_account\_calendar\_events permissionto create events on this calendar, and allow users to view thiscalendar and its events. | | `auto_subscribe` | `boolean` | When true, users will automatically see events from this account in theircalendar, even if they haven't manually added that calendar. | #### Example Request: ```bash curl https:///api/v1/account_calendars/204 \ -X PUT \ -H 'Authorization: Bearer ' \ -d 'visible=false' \ -d 'auto_subscribe=false' ``` Returns an [AccountCalendar](#accountcalendar) object. ## [Update several calendars](#method.account_calendars_api.bulk_update) [AccountCalendarsApiController#bulk\_update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `PUT /api/v1/accounts/:account_id/account_calendars` **Scope:** `url:PUT|/api/v1/accounts/:account_id/account_calendars` Set visibility and/or auto\_subscribe on many calendars simultaneously. Requires the `manage_account_calendar_visibility` permission on the account. Accepts a JSON array of objects containing 2-3 keys each: `id` (the account's id, required), `visible` (a boolean indicating whether the account calendar is visible), and `auto_subscribe` (a boolean indicating whether users should see these events in their calendar without manually subscribing). Returns the count of updated accounts. #### Example Request: ```bash curl https:///api/v1/accounts/1/account_calendars \ -X PUT \ -H 'Authorization: Bearer ' \ --data '[{"id": 1, "visible": true, "auto_subscribe": false}, {"id": 13, "visible": false, "auto_subscribe": true}]' ``` ## [List all account calendars](#method.account_calendars_api.all_calendars) [AccountCalendarsApiController#all\_calendars](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `GET /api/v1/accounts/:account_id/account_calendars` **Scope:** `url:GET|/api/v1/accounts/:account_id/account_calendars` Returns a paginated list of account calendars for the provided account and its first level of sub-accounts. Includes hidden calendars in the response. Requires the `manage_account_calendar_visibility` permission. #### Request Parameters: | Parameter | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search_term` | `string` | When included, searches all descendent accounts of provided account for theterm. Returns matching results. Term must be at least 2 characters. Can becombined with a filter value. | | `filter` | `string` | When included, only returns calendars that are either visible or hidden. Canbe combined with a search term. Allowed values: visible, hidden | #### Example Request: ```bash curl https:///api/v1/accounts/1/account_calendars \ -H 'Authorization: Bearer ' ``` Returns a list of [AccountCalendar](#accountcalendar) objects. ## [Count of all visible account calendars](#method.account_calendars_api.visible_calendars_count) [AccountCalendarsApiController#visible\_calendars\_count](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_calendars_api_controller.rb) #### `GET /api/v1/accounts/:account_id/visible_calendars_count` **Scope:** `url:GET|/api/v1/accounts/:account_id/visible_calendars_count` Returns the number of visible account calendars. #### Example Request: ```bash curl https:///api/v1/accounts/1/visible_calendars_count \ -H 'Authorization: Bearer ' ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Account Domain Lookups ## [Search account domains](#method.account_domain_lookups.search) #### `GET /api/v1/accounts/search` **Scope:** `url:GET|/api/v1/accounts/search` Returns a list of up to 5 matching account domains Partial match on name / domain are supported #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | -------------- | | `name` | `string` | campus name | | `domain` | `string` | no description | | `latitude` | `number` | no description | | `longitude` | `number` | no description | #### Example Request: ```bash curl https:///api/v1/accounts/search \ -G -H 'Authorization: Bearer ' \ -d 'name=utah' ``` #### Example Response: ```js [ { "name": "University of Utah", "domain": "utah.edu", "distance": null, // distance is always nil, but preserved in the api response for backwards compatibility "authentication_provider": "canvas", // which authentication_provider param to pass to the oauth flow; may be NULL }, ... ] ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Account Notifications API for account notifications. #### An AccountNotification object looks like: ```js { // The subject of the notifications "subject": "Attention Students", // The message to be sent in the notification. "message": "This is a test of the notification system.", // When to send out the notification. "start_at": "2013-08-28T23:59:00-06:00", // When to expire the notification. "end_at": "2013-08-29T23:59:00-06:00", // The icon to display with the message. Defaults to warning. "icon": "information", // (Deprecated) The roles to send the notification to. If roles is not passed // it defaults to all roles "roles": ["StudentEnrollment"], // The roles to send the notification to. If roles is not passed it defaults to // all roles "role_ids": [1], // The author of the notification. Available only to admins using include_all. "author": {"id":1,"name":"John Doe"} } ``` ## [Index of active global notification for the user](#method.account_notifications.user_index) [AccountNotificationsController#user\_index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `GET /api/v1/accounts/:account_id/account_notifications` **Scope:** `url:GET|/api/v1/accounts/:account_id/account_notifications` Returns a list of all global notifications in the account for the current user Any notifications that have been closed by the user will not be returned, unless a include\_past parameter is passed in as true. Admins can request all global notifications for the account by passing in an include\_all parameter. #### Request Parameters: | Parameter | Type | Description | | ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------- | | `include_past` | `boolean` | Include past and dismissed global announcements. | | `include_all` | `boolean` | Include all global announcements, regardless of user's role or availability date. Only available to account admins. | | `show_is_closed` | `boolean` | Include a flag for each notification indicating whether it has been read by the user. | #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/users/self/account_notifications ``` Returns a list of [AccountNotification](#accountnotification) objects. ## [Show a global notification](#method.account_notifications.show) [AccountNotificationsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `GET /api/v1/accounts/:account_id/account_notifications/:id` **Scope:** `url:GET|/api/v1/accounts/:account_id/account_notifications/:id` Returns a global notification for the current user A notification that has been closed by the user will not be returned #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/users/self/account_notifications/4 ``` Returns an [AccountNotification](#accountnotification) object. ## [Create a global notification](#method.account_notifications.create) [AccountNotificationsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `POST /api/v1/accounts/:account_id/account_notifications` **Scope:** `url:POST|/api/v1/accounts/:account_id/account_notifications` Create and return a new global notification for an account. #### Request Parameters: | Parameter | Type | Description | | -------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_notification[subject]` | Required `string` | The subject of the notification. | | `account_notification[message]` | Required `string` | The message body of the notification. | | `account_notification[start_at]` | Required `DateTime` | The start date and time of the notification in ISO8601 format.e.g. 2014-01-01T01:00Z | | `account_notification[end_at]` | Required `DateTime` | The end date and time of the notification in ISO8601 format.e.g. 2014-01-01T01:00Z | | `account_notification[icon]` | `string` | The icon to display with the notification.Note: Defaults to warning. Allowed values: warning, information, question, error, calendar | | `account_notification_roles[]` | `string` | The role(s) to send global notification to. Note: ommitting this field will send to everyoneExample:account\_notification\_roles: \["StudentEnrollment", "TeacherEnrollment"] | #### Example Request: ```bash curl -X POST -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/account_notifications \ -d 'account_notification[subject]=New notification' \ -d 'account_notification[start_at]=2014-01-01T00:00:00Z' \ -d 'account_notification[end_at]=2014-02-01T00:00:00Z' \ -d 'account_notification[message]=This is a global notification' ``` #### Example Response: ```js { "subject": "New notification", "start_at": "2014-01-01T00:00:00Z", "end_at": "2014-02-01T00:00:00Z", "message": "This is a global notification" } ``` ## [Update a global notification](#method.account_notifications.update) [AccountNotificationsController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `PUT /api/v1/accounts/:account_id/account_notifications/:id` **Scope:** `url:PUT|/api/v1/accounts/:account_id/account_notifications/:id` Update global notification for an account. #### Request Parameters: | Parameter | Type | Description | | -------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_notification[subject]` | `string` | The subject of the notification. | | `account_notification[message]` | `string` | The message body of the notification. | | `account_notification[start_at]` | `DateTime` | The start date and time of the notification in ISO8601 format.e.g. 2014-01-01T01:00Z | | `account_notification[end_at]` | `DateTime` | The end date and time of the notification in ISO8601 format.e.g. 2014-01-01T01:00Z | | `account_notification[icon]` | `string` | The icon to display with the notification. Allowed values: `warning`, `information`, `question`, `error`, `calendar` | | `account_notification_roles[]` | `string` | The role(s) to send global notification to. Note: ommitting this field will send to everyoneExample:account\_notification\_roles: \["StudentEnrollment", "TeacherEnrollment"] | #### Example Request: ```bash curl -X PUT -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/account_notifications/1 \ -d 'account_notification[subject]=New notification' \ -d 'account_notification[start_at]=2014-01-01T00:00:00Z' \ -d 'account_notification[end_at]=2014-02-01T00:00:00Z' \ -d 'account_notification[message]=This is a global notification' ``` #### Example Response: ```js { "subject": "New notification", "start_at": "2014-01-01T00:00:00Z", "end_at": "2014-02-01T00:00:00Z", "message": "This is a global notification" } ``` ## [Close notification for user. Destroy notification for admin](#method.account_notifications.user_close_notification) [AccountNotificationsController#user\_close\_notification](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb) #### `DELETE /api/v1/accounts/:account_id/account_notifications/:id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/account_notifications/:id` If the current user no longer wants to see this account notification, it can be closed with this call. This affects the current user only. If the current user is an admin and they pass a remove parameter with a value of "true", the account notification will be destroyed. This affects all users. #### Request Parameters: | Parameter | Type | Description | | --------- | --------- | --------------------------------- | | `remove` | `boolean` | Destroy the account notification. | #### Example Request: ```bash curl -X DELETE -H 'Authorization: Bearer ' \ https:///api/v1/accounts/2/account_notifications/4 ``` Returns an [AccountNotification](#accountnotification) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Account Reports API for accessing account reports. #### A Report object looks like: ```js { // The unique identifier for the report. "id": 1, // The type of report. "report": "sis_export_csv", // The url to the report download. "file_url": "https://example.com/some/path", // The attachment api object of the report. Only available after the report has // completed. "attachment": null, // The status of the report "status": "complete", // The date and time the report was created. "created_at": "2013-12-01T23:59:00-06:00", // The date and time the report started processing. "started_at": "2013-12-02T00:03:21-06:00", // The date and time the report finished processing. "ended_at": "2013-12-02T00:03:21-06:00", // The time (in seconds) the report has been waiting to run, has been running so // far, or took to run to completion, depending on its current state. "run_time": 33.3, // The report parameters "parameters": {"course_id":2,"start_at":"2012-07-13T10:55:20-06:00","end_at":"2012-07-13T10:55:20-06:00"}, // The progress of the report "progress": 100, // This is the current line count being written to the report. It updates every // 1000 records. "current_line": 12000, // The user that initiated the account report. See the Users API for details. "user": null } ``` #### A ReportParameters object looks like: ```js // The parameters returned will vary for each report. { // The canvas id of the term to get grades from "enrollment_term_id": 2, // If true, deleted objects will be included. If false, deleted objects will be // omitted. "include_deleted": false, // The id of the course to report on "course_id": 2, // The sort order for the csv, Options: 'users', 'courses', 'outcomes'. "order": "users", // If true, user data will be included. If false, user data will be omitted. "users": false, // If true, account data will be included. If false, account data will be // omitted. "accounts": false, // If true, term data will be included. If false, term data will be omitted. "terms": false, // If true, course data will be included. If false, course data will be omitted. "courses": false, // If true, section data will be included. If false, section data will be // omitted. "sections": false, // If true, enrollment data will be included. If false, enrollment data will be // omitted. "enrollments": false, // If true, group data will be included. If false, group data will be omitted. "groups": false, // If true, data for crosslisted courses will be included. If false, data for // crosslisted courses will be omitted. "xlist": false, "sis_terms_csv": 1, "sis_accounts_csv": 1, // If true, enrollment state will be included. If false, enrollment state will // be omitted. Defaults to false. "include_enrollment_state": false, // Include enrollment state. Defaults to 'all' Options: ['active'| 'invited'| // 'creation_pending'| 'deleted'| 'rejected'| 'completed'| 'inactive'| 'all'] "enrollment_state": ["all"], // The beginning date for submissions. Max time range is 2 weeks. "start_at": "2012-07-13T10:55:20-06:00", // The end date for submissions. Max time range is 2 weeks. "end_at": "2012-07-13T10:55:20-06:00" } ``` ## [List Available Reports](#method.account_reports.available_reports) [AccountReportsController#available\_reports](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `GET /api/v1/accounts/:account_id/reports` **Scope:** `url:GET|/api/v1/accounts/:account_id/reports` Returns a paginated list of reports for the current context. #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Array of additional information to include."description\_html":: an HTML description of the report, with example output"parameters\_html":: an HTML form for the report parameters Allowed values: description\_html, params\_html | #### API response field: * name The name of the report. * parameters The parameters will vary for each report * last\_run \[Report] The last run of the report. This will be null if the report has never been run. #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts//reports/ ``` #### Example Response: ```js [ { "report":"student_assignment_outcome_map_csv", "title":"Student Competency", "parameters":null, "last_run": { "id": 1, "report": "student_assignment_outcome_map_csv", "file_url": "https://example.com/some/path", "status": "complete", "created_at": "2013-12-01T23:59:00-06:00", "started_at": "2013-12-02T00:03:21-06:00", "ended_at": "2013-12-02T00:03:21-06:00" }, { "report":"grade_export_csv", "title":"Grade Export", "parameters":{ "term":{ "description":"The canvas id of the term to get grades from", "required":true } }, "last_run": null } ] ``` ## [Start a Report](#method.account_reports.create) [AccountReportsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `POST /api/v1/accounts/:account_id/reports/:report` **Scope:** `url:POST|/api/v1/accounts/:account_id/reports/:report` Generates a report instance for the account. Note that "report" in the request must match one of the available report names. To fetch a list of available report names and parameters for each report (including whether or not those parameters are required), see [List Available Reports](#method.account_reports.available_reports). #### Request Parameters: | Parameter | Type | Description | | -------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `parameters[]` | `Hash` | The parameters will vary for each report. To fetch a listof available parameters for each report, see List Available Reports.A few example parameters have been provided below. Note that the exampleparameters provided below may not be valid for every report. | | `parameters[skip_message]` | `boolean` | If true, no message will be sentto the user upon completion of the report. | | `parameters[course_id]` | `integer` | The id of the course to report on.Note: this parameter has been listed to serve as an example and may not bevalid for every report. | | `parameters[users]` | `boolean` | If true, user data will be included. Iffalse, user data will be omitted. Note: this parameter has been listed toserve as an example and may not be valid for every report. | #### Example Request: ```bash curl -X POST \ https:///api/v1/accounts/1/reports/provisioning_csv \ -H 'Authorization: Bearer ' \ -H 'Content-Type: multipart/form-data' \ -F 'parameters[users]=true' \ -F 'parameters[courses]=true' \ -F 'parameters[enrollments]=true' ``` Returns a [Report](/services/canvas/resources/course_reports#report) object. ## [Index of Reports](#method.account_reports.index) [AccountReportsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `GET /api/v1/accounts/:account_id/reports/:report` **Scope:** `url:GET|/api/v1/accounts/:account_id/reports/:report` Shows all reports that have been run for the account of a specific type. #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts//reports/ ``` Returns a list of [Report](/services/canvas/resources/course_reports#report) objects. ## [Status of a Report](#method.account_reports.show) [AccountReportsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `GET /api/v1/accounts/:account_id/reports/:report/:id` **Scope:** `url:GET|/api/v1/accounts/:account_id/reports/:report/:id` Returns the status of a report. #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts//reports// ``` Returns a [Report](/services/canvas/resources/course_reports#report) object. ## [Delete a Report](#method.account_reports.destroy) [AccountReportsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `DELETE /api/v1/accounts/:account_id/reports/:report/:id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/reports/:report/:id` Deletes a generated report instance. #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ -X DELETE \ https:///api/v1/accounts//reports// ``` Returns a [Report](/services/canvas/resources/course_reports#report) object. ## [Abort a Report](#method.account_reports.abort) [AccountReportsController#abort](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) #### `PUT /api/v1/accounts/:account_id/reports/:report/:id/abort` **Scope:** `url:PUT|/api/v1/accounts/:account_id/reports/:report/:id/abort` Abort a report in progress #### Example Request: ```bash curl -H 'Authorization: Bearer ' \ -X PUT \ https:///api/v1/accounts//reports///abort ``` Returns a [Report](/services/canvas/resources/course_reports#report) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Accounts API for accessing account data. #### An Account object looks like: ```js { // the ID of the Account object "id": 2, // The display name of the account "name": "Canvas Account", // The UUID of the account "uuid": "WvAHhY5FINzq5IyRIJybGeiXyFkG3SqHUPb7jZY5", // The account's parent ID, or null if this is the root account "parent_account_id": 1, // The ID of the root account, or null if this is the root account "root_account_id": 1, // The storage quota for the account in megabytes, if not otherwise specified "default_storage_quota_mb": 500, // The storage quota for a user in the account in megabytes, if not otherwise // specified "default_user_storage_quota_mb": 50, // The storage quota for a group in the account in megabytes, if not otherwise // specified "default_group_storage_quota_mb": 50, // The default time zone of the account. Allowed time zones are // {http://www.iana.org/time-zones IANA time zones} or friendlier // {http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html Ruby on Rails // time zones}. "default_time_zone": "America/Denver", // The friendly Ruby on Rails name of the account's default time zone. Since // several Rails time zones can share a single IANA identifier (the value // returned in default_time_zone), this field disambiguates which one is // configured. "default_time_zone_friendly_name": "Mountain Time (US & Canada)", // The account's identifier in the Student Information System. Only included if // the user has permission to view SIS information. "sis_account_id": "123xyz", // The account's identifier in the Student Information System. Only included if // the user has permission to view SIS information. "integration_id": "123xyz", // The id of the SIS import if created through SIS. Only included if the user // has permission to manage SIS information. "sis_import_id": 12, // The number of courses directly under the account (available via include) "course_count": 10, // The number of sub-accounts directly under the account (available via include) "sub_account_count": 10, // The account's identifier that is sent as context_id in LTI launches. "lti_guid": "123xyz", // The state of the account. Can be 'active' or 'deleted'. "workflow_state": "active" } ``` #### A TermsOfService object looks like: ```js { // Terms Of Service id "id": 1, // The given type for the Terms of Service "terms_type": "default", // Boolean dictating if the user must accept Terms of Service "passive": false, // The id of the root account that owns the Terms of Service "account_id": 1, // Content of the Terms of Service "content": "To be or not to be that is the question", // The type of self registration allowed "self_registration_type": "["none", "observer", "all"]" } ``` #### A HelpLink object looks like: ```js { // The ID of the help link "id": "instructor_question", // The name of the help link "text": "Ask Your Instructor a Question", // The description of the help link "subtext": "Questions are submitted to your instructor", // The URL of the help link "url": "#teacher_feedback", // The type of the help link "type": "default", // The roles that have access to this help link "available_to": ["user", "student", "teacher", "admin", "observer", "unenrolled"] } ``` #### A HelpLinks object looks like: ```js { // Help link button title "help_link_name": "Help And Policies", // Help link button icon "help_link_icon": "help", // Help links defined by the account. Could include default help links. "custom_help_links": [{"id":"link1","text":"Custom Link!","subtext":"Something something.","url":"https:\/\/google.com","type":"custom","available_to":["user","student","teacher","admin","observer","unenrolled"],"is_featured":true,"is_new":false,"feature_headline":"Check this out!"}], // Default help links provided when account has not set help links of their own. "default_help_links": [{"available_to":["student"],"text":"Ask Your Instructor a Question","subtext":"Questions are submitted to your instructor","url":"#teacher_feedback","type":"default","id":"instructor_question","is_featured":false,"is_new":true,"feature_headline":""}, {"available_to":["user","student","teacher","admin","observer","unenrolled"],"text":"Search the Canvas Guides","subtext":"Find answers to common questions","url":"https:\/\/community.canvaslms.com\/t5\/Guides\/ct-p\/guides","type":"default","id":"search_the_canvas_guides","is_featured":false,"is_new":false,"feature_headline":""}, {"available_to":["user","student","teacher","admin","observer","unenrolled"],"text":"Report a Problem","subtext":"If Canvas misbehaves, tell us about it","url":"#create_ticket","type":"default","id":"report_a_problem","is_featured":false,"is_new":false,"feature_headline":""}] } ``` ## [List accounts](#method.accounts.index) [AccountsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts` **Scope:** `url:GET|/api/v1/accounts` A paginated list of accounts that the current user can view or manage. Typically, students and even teachers will get an empty list in response, only account admins can view the accounts that they are in. #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Array of additional information to include."lti\_guid":: the 'tool\_consumer\_instance\_guid' that will be sent for this account on LTI launches"registration\_settings":: returns info about the privacy policy and terms of use"services":: returns services and whether they are enabled (requires account management permissions)"course\_count":: returns the number of courses directly under each account"sub\_account\_count":: returns the number of sub-accounts directly under each account Allowed values: lti\_guid, registration\_settings, services, course\_count, sub\_account\_count | Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [List horizon accounts](#method.accounts.horizon_accounts) [AccountsController#horizon\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/horizon_accounts` **Scope:** `url:GET|/api/v1/horizon_accounts` A paginated list of horizon accounts that the current user can view or manage. Returns all accounts with the horizon\_account setting enabled. If there are any horizon accounts and the user has access to Site Admin, Site Admin will also be included in the results. Typically, students and even teachers will get an empty list in response, only account admins can view the accounts that they are in. #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Array of additional information to include."lti\_guid":: the 'tool\_consumer\_instance\_guid' that will be sent for this account on LTI launches"registration\_settings":: returns info about the privacy policy and terms of use"services":: returns services and whether they are enabled (requires account management permissions)"course\_count":: returns the number of courses directly under each account"sub\_account\_count":: returns the number of sub-accounts directly under each account"site\_admin":: returns true if the account is the Site Admin account (only included if true) Allowed values: lti\_guid, registration\_settings, services, course\_count, sub\_account\_count, site\_admin | Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [Get accounts that admins can manage](#method.accounts.manageable_accounts) [AccountsController#manageable\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/manageable_accounts` **Scope:** `url:GET|/api/v1/manageable_accounts` A paginated list of accounts where the current user has permission to create or manage courses. List will be empty for students and teachers as only admins can view which accounts they are in. Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [Get accounts that users can create courses in](#method.accounts.course_creation_accounts) [AccountsController#course\_creation\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/course_creation_accounts` **Scope:** `url:GET|/api/v1/course_creation_accounts` A paginated list of accounts where the current user has permission to create courses. Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [List accounts for course admins](#method.accounts.course_accounts) [AccountsController#course\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/course_accounts` **Scope:** `url:GET|/api/v1/course_accounts` A paginated list of accounts that the current user can view through their admin course enrollments. (Teacher, TA, or designer enrollments). Only returns "id", "name", "workflow\_state", "root\_account\_id" and "parent\_account\_id" Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [Get a single account](#method.accounts.show) [AccountsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:id` **Scope:** `url:GET|/api/v1/accounts/:id` Retrieve information on an individual account, given by id or sis sis\_account\_id. Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. ## [Settings](#method.accounts.show_settings) [AccountsController#show\_settings](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/settings` **Scope:** `url:GET|/api/v1/accounts/:account_id/settings` Returns a JSON object containing a subset of settings for the specified account. It's possible an empty set will be returned if no settings are applicable. The caller must be an Account admin with the manage\_account\_settings permission. #### Example Request: ```bash curl https:///api/v1/accounts//settings \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js {"microsoft_sync_enabled": true, "microsoft_sync_login_attribute_suffix": false} ``` ## [List environment settings](#method.accounts.environment) [AccountsController#environment](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/settings/environment` **Scope:** `url:GET|/api/v1/settings/environment` Return a hash of global settings for the root account This is the same information supplied to the web interface as +ENV.SETTINGS+. #### Example Request: ```bash curl 'http:///api/v1/settings/environment' \ -H "Authorization: Bearer " ``` #### Example Response: ```js { "calendar_contexts_limit": 10, "open_registration": false, ...} ``` ## [Permissions](#method.accounts.permissions) [AccountsController#permissions](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/permissions` **Scope:** `url:GET|/api/v1/accounts/:account_id/permissions` Returns permission information for the calling user and the given account. You may use `self` as the account id to check permissions against the domain root account. The caller must have an account role or admin (teacher/TA/designer) enrollment in a course in the account. See also the [Course](https://developerdocs.instructure.com/services/canvas/resources/pages/Dq3HF46TIgKustPuq4C9#method.courses.permissions) and [Group](https://developerdocs.instructure.com/services/canvas/resources/pages/2YyNPW0XHYoLadMGQAZY#method.groups.permissions) counterparts. #### Request Parameters: | Parameter | Type | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `permissions[]` | `string` | List of permissions to check against the authenticated user.Permission names are documented in the List assignable permissions endpoint. | #### Example Request: ```bash curl https:///api/v1/accounts/self/permissions \ -H 'Authorization: Bearer ' \ -d 'permissions[]=manage_account_memberships' \ -d 'permissions[]=become_user' ``` #### Example Response: ```js {'manage_account_memberships': 'false', 'become_user': 'true'} ``` ## [Get the sub-accounts of an account](#method.accounts.sub_accounts) [AccountsController#sub\_accounts](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/sub_accounts` **Scope:** `url:GET|/api/v1/accounts/:account_id/sub_accounts` List accounts that are sub-accounts of the given account. #### Request Parameters: | Parameter | Type | Description | | ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `recursive` | `boolean` | If true, the entire account tree underneaththis account will be returned (though still paginated). If false, onlydirect sub-accounts of this account will be returned. Defaults to false. | | `order` | `string` | Sorts the accounts by id or name.Only applies when recursive is false. Defaults to id. Allowed values: id, name | | `include[]` | `string` | Array of additional information to include."course\_count":: returns the number of courses directly under each account"sub\_account\_count":: returns the number of sub-accounts directly under each account Allowed values: course\_count, sub\_account\_count | #### Example Request: ```bash curl https:///api/v1/accounts//sub_accounts \ -H 'Authorization: Bearer ' ``` Returns a list of [Account](/services/canvas/resources/accounts_-lti#account) objects. ## [Get the Terms of Service](#method.accounts.terms_of_service) [AccountsController#terms\_of\_service](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/terms_of_service` **Scope:** `url:GET|/api/v1/accounts/:account_id/terms_of_service` Returns the terms of service for that account Returns a [TermsOfService](#termsofservice) object. ## [Get help links](#method.accounts.help_links) [AccountsController#help\_links](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/help_links` **Scope:** `url:GET|/api/v1/accounts/:account_id/help_links` Returns the help links for that account Returns a [HelpLinks](#helplinks) object. ## [Get the manually-created courses sub-account for the domain root account](#method.accounts.manually_created_courses_account) [AccountsController#manually\_created\_courses\_account](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/manually_created_courses_account` **Scope:** `url:GET|/api/v1/manually_created_courses_account` Returns the sub-account that contains manually created courses for the domain root account. Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. ## [List active courses in an account](#method.accounts.courses_api) [AccountsController#courses\_api](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `GET /api/v1/accounts/:account_id/courses` **Scope:** `url:GET|/api/v1/accounts/:account_id/courses` Retrieve a paginated list of courses in this account. #### Request Parameters: | Parameter | Type | Description | | ----------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `with_enrollments` | `boolean` | If true, include only courses with at least one enrollment. If false,include only courses with no enrollments. If not present, do not filteron course enrollment status. | | `enrollment_type[]` | `string` | If set, only return courses that have at least one user enrolled inin the course with one of the specified enrollment types. Allowed values: teacher, student, ta, observer, designer | | `enrollment_workflow_state[]` | `string` | If set, only return courses that have at least one user enrolled inin the course with one of the specified enrollment workflow states. Allowed values: active, completed, deleted, invited, pending, creation\_pending, rejected, inactive | | `published` | `boolean` | If true, include only published courses. If false, exclude publishedcourses. If not present, do not filter on published status. | | `completed` | `boolean` | If true, include only completed courses (these may be in state'completed', or their enrollment term may have ended). If false, excludecompleted courses. If not present, do not filter on completed status. | | `blueprint` | `boolean` | If true, include only blueprint courses. If false, exclude them.If not present, do not filter on this basis. | | `blueprint_associated` | `boolean` | If true, include only courses that inherit content from a blueprint course.If false, exclude them. If not present, do not filter on this basis. | | `public` | `boolean` | If true, include only public courses. If false, exclude them.If not present, do not filter on this basis. | | `by_teachers[]` | `integer` | List of User IDs of teachers; if supplied, include only courses taught byone of the referenced users. | | `by_subaccounts[]` | `integer` | List of Account IDs; if supplied, include only courses associated with oneof the referenced subaccounts. | | `hide_enrollmentless_courses` | `boolean` | If present, only return courses that have at least one enrollment.Equivalent to 'with\_enrollments=true'; retained for compatibility. | | `state[]` | `string` | If set, only return courses that are in the given state(s). By default,all states but "deleted" are returned. Allowed values: created, claimed, available, completed, deleted, all | | `enrollment_term_id[]` | `integer` | If set, only includes courses from the specified terms. Can be either a single ID oran array of enrollment term IDs. | | `search_term` | `string` | The partial course name, code, or full ID to match and return in the results list. Must be at least 3 characters. | | `include[]` | `string` | - All explanations can be seen in the Course API index documentation- "sections", "needs\_grading\_count" and "total\_scores" are not valid options at the account level Allowed values: syllabus\_body, term, course\_progress, storage\_quota\_used\_mb, total\_students, teachers, account\_name, concluded, post\_manually | | `sort` | `string` | The column to sort results by. Allowed values: `course_status`, `course_name`, `sis_course_id`, `teacher`, `account_name` | | `order` | `string` | The order to sort the given column by. Allowed values: `asc`, `desc` | | `search_by` | `string` | The filter to search by. "course" searches for course names, course codes,and SIS IDs. "teacher" searches for teacher names Allowed values: course, teacher | | `starts_before` | `Date` | If set, only return courses that start before the value (inclusive)or their enrollment term starts before the value (inclusive)or both the course's start\_at and the enrollment term's start\_at are set to null.The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. | | `ends_after` | `Date` | If set, only return courses that end after the value (inclusive)or their enrollment term ends after the value (inclusive)or both the course's end\_at and the enrollment term's end\_at are set to null.The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. | | `homeroom` | `boolean` | If set, only return homeroom courses. | Returns a list of [Course](/services/canvas/resources/courses#course) objects. ## [Update an account](#method.accounts.update) [AccountsController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `PUT /api/v1/accounts/:id` **Scope:** `url:PUT|/api/v1/accounts/:id` Update an existing account. #### Request Parameters: | Parameter | Type | Description | | ------------------------------------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account[name]` | `string` | Updates the account name | | `account[sis_account_id]` | `string` | Updates the account sis\_account\_idMust have manage\_sis permission and must not be a root\_account. | | `account[default_time_zone]` | `string` | The default time zone of the account. Allowed time zones areIANA time zones or friendlierRuby on Rails time zones. | | `account[default_storage_quota_mb]` | `integer` | The default course storage quota to be used, if not otherwise specified. | | `account[default_user_storage_quota_mb]` | `integer` | The default user storage quota to be used, if not otherwise specified. | | `account[default_group_storage_quota_mb]` | `integer` | The default group storage quota to be used, if not otherwise specified. | | `account[course_template_id]` | `integer` | The ID of a course to be used as a template for all newly created courses.Empty means to inherit the setting from parent account, 0 means to notuse a template even if a parent account has one set. The course must bemarked as a template. | | `account[parent_account_id]` | `integer` | The ID of a parent account to move the account to. The new parent accountmust be in the same root account as the original. The hierarchy ofsub-accounts will be preserved in the new parent account. The caller mustbe an administrator in both the original parent account and the new parentaccount. | | `account[settings][restrict_student_past_view][value]` | `boolean` | Restrict students from viewing courses after end date | | `account[settings][restrict_student_past_view][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][restrict_student_future_view][value]` | `boolean` | Restrict students from viewing courses before start date | | `account[settings][microsoft_sync_enabled]` | `boolean` | Determines whether this account has Microsoft Teams Sync enabled or not.Note that if you are altering Microsoft Teams sync settings you must enablethe Microsoft Group enrollment syncing feature flag. In addition, if you are enablingMicrosoft Teams sync, you must also specify a tenant, login attribute, and a remote attribute.Specifying a suffix to use is optional. | | `account[settings][microsoft_sync_tenant]` | `string` | The tenant this account should use when using Microsoft Teams Sync.This should be an Azure Active Directory domain name. | | `account[settings][microsoft_sync_login_attribute]` | `string` | The attribute this account should use to lookup users when using Microsoft Teams Sync.Must be one of "sub", "email", "oid", "preferred\_username", or "integration\_id". | | `account[settings][microsoft_sync_login_attribute_suffix]` | `string` | A suffix that will be appended to the result of the login attribute when associatingCanvas users with Microsoft users. Must be under 255 characters and contain no whitespace.This field is optional. | | `account[settings][microsoft_sync_remote_attribute]` | `string` | The Active Directory attribute to use when associating Canvas users with Microsoft users.Must be one of "mail", "mailNickname", or "userPrincipalName". | | `account[settings][restrict_student_future_view][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][lock_all_announcements][value]` | `boolean` | Disable comments on announcements | | `account[settings][lock_all_announcements][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][usage_rights_required][value]` | `boolean` | Copyright and license information must be provided for files before they are published. | | `account[settings][usage_rights_required][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][restrict_student_future_listing][value]` | `boolean` | Restrict students from viewing future enrollments in course list | | `account[settings][restrict_student_future_listing][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][conditional_release][value]` | `boolean` | Enable or disable individual learning paths for students based on assessment | | `account[settings][conditional_release][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][enable_course_paces][value]` | `boolean` | Enable or disable course pacing | | `account[settings][enable_course_paces][locked]` | `boolean` | Lock this setting for sub-accounts and courses | | `account[settings][suppress_notifications]` | `boolean` | Suppress notification messages from being created and sent. When set to+true+, all notifications are suppressed. When set to an array ofnotification category slugs (e.g. +\["grading", "announcement"]+), onlynotifications in those categories are suppressed. Set to +false+ toallow all notifications. Root account setting only. | | `account[settings][password_policy]` | `Hash` | Hash of optional password policy configuration parameters for a root account+allow\_login\_suspension+ boolean:: Allow suspension of user logins upon reaching maximum\_login\_attempts+require\_number\_characters+ boolean:: Require the use of number characters when setting up a new password+require\_symbol\_characters+ boolean:: Require the use of symbol characters when setting up a new password+minimum\_character\_length+ integer:: Minimum number of characters required for a new password+maximum\_login\_attempts+ integer:: Maximum number of login attempts before a user is locked outRequired feature option:Enhance password options | | `account[settings][enable_as_k5_account][value]` | `boolean` | Enable or disable Canvas for Elementary for this account | | `account[settings][use_classic_font_in_k5][value]` | `boolean` | Whether or not the classic font is used on the dashboard. Only applies if enable\_as\_k5\_account is true. | | `account[settings][horizon_account][value]` | `boolean` | Enable or disable Canvas Career for this account | | `override_sis_stickiness` | `boolean` | Default is true. If false, any fields containing “sticky” changes will not be updated.See SIS CSV Format documentation for information on which fields can have SIS stickiness | | `account[settings][lock_outcome_proficiency][value]` | `boolean` | \[DEPRECATED] Restrict instructors from changing mastery scale | | `account[lock_outcome_proficiency][locked]` | `boolean` | \[DEPRECATED] Lock this setting for sub-accounts and courses | | `account[settings][lock_proficiency_calculation][value]` | `boolean` | \[DEPRECATED] Restrict instructors from changing proficiency calculation method | | `account[lock_proficiency_calculation][locked]` | `boolean` | \[DEPRECATED] Lock this setting for sub-accounts and courses | | `account[services]` | `Hash` | Give this a set of keys and boolean values to enable or disable services matching the keys | #### Example Request: ```bash curl https:///api/v1/accounts/ \ -X PUT \ -H 'Authorization: Bearer ' \ -d 'account[name]=New account name' \ -d 'account[default_time_zone]=Mountain Time (US & Canada)' \ -d 'account[default_storage_quota_mb]=450' ``` Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. ## [Delete a user from the root account](#method.accounts.remove_user) [AccountsController#remove\_user](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `DELETE /api/v1/accounts/:account_id/users/:user_id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/users/:user_id` Delete a user record from a Canvas root account. If a user is associated with multiple root accounts (in a multi-tenant instance of Canvas), this action will NOT remove them from the other accounts. WARNING: This API will allow a user to remove themselves from the account. If they do this, they won't be able to make API calls or log into Canvas at that account. #### Example Request: ```bash curl https:///api/v1/accounts/3/users/5 \ -H 'Authorization: Bearer ' \ -X DELETE ``` Returns an [User](/services/canvas/resources/users#user) object. ## [Delete multiple users from the root account](#method.accounts.remove_users) [AccountsController#remove\_users](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `DELETE /api/v1/accounts/:account_id/users` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/users` Delete multiple users from a Canvas root account. If a user is associated with multiple root accounts (in a multi-tenant instance of Canvas), this action will NOT remove them from the other accounts. WARNING: This API will allow a user to remove themselves from the account. If they do this, they won't be able to make API calls or log into Canvas at that account. #### Example Request: ```bash curl https:///api/v1/accounts/3/users \ -H 'Authorization: Bearer ' \ -X DELETE -d 'user_ids[]=1' \ -d 'user_ids[]=2' ``` Returns a [Progress](/services/canvas/resources/progress#progress) object. ## [Update multiple users](#method.accounts.update_users) [AccountsController#update\_users](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `PUT /api/v1/accounts/:account_id/users/bulk_update` **Scope:** `url:PUT|/api/v1/accounts/:account_id/users/bulk_update` Updates multiple users in bulk. #### Request Parameters: | Parameter | Type | Description | | ---------- | -------- | ------------------------------------------------------------ | | `user_ids` | `string` | \[Array\]The IDs of the users to update. | | `user` | `Hash` | The attributes to update for each user. | #### Example Request: ```bash curl https:///api/v1/accounts/3/users/bulk_update \ -X PUT \ -H 'Authorization: Bearer ' \ -d 'user_ids[]=1' \ -d 'user_ids[]=2' \ -d 'user[event]=suspend' ``` Returns a [Progress](/services/canvas/resources/progress#progress) object. ## [Restore a deleted user from a root account](#method.accounts.restore_user) [AccountsController#restore\_user](https://github.com/instructure/canvas-lms/blob/master/app/controllers/accounts_controller.rb) #### `PUT /api/v1/accounts/:account_id/users/:user_id/restore` **Scope:** `url:PUT|/api/v1/accounts/:account_id/users/:user_id/restore` Restore a user record along with the most recently deleted pseudonym from a Canvas root account. #### Example Request: ```bash curl https:///api/v1/accounts/3/users/5/restore \ -H 'Authorization: Bearer ' \ -X PUT ``` Returns an [User](/services/canvas/resources/users#user) object. ## [Create a new sub-account](#method.sub_accounts.create) [SubAccountsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/sub_accounts_controller.rb) #### `POST /api/v1/accounts/:account_id/sub_accounts` **Scope:** `url:POST|/api/v1/accounts/:account_id/sub_accounts` Add a new sub-account to a given account. #### Request Parameters: | Parameter | Type | Description | | ----------------------------------------- | ----------------- | ------------------------------------------------------------------------ | | `account[name]` | Required `string` | The name of the new sub-account. | | `account[sis_account_id]` | `string` | The account's identifier in the Student Information System. | | `account[default_storage_quota_mb]` | `integer` | The default course storage quota to be used, if not otherwise specified. | | `account[default_user_storage_quota_mb]` | `integer` | The default user storage quota to be used, if not otherwise specified. | | `account[default_group_storage_quota_mb]` | `integer` | The default group storage quota to be used, if not otherwise specified. | Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. ## [Delete a sub-account](#method.sub_accounts.destroy) [SubAccountsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/sub_accounts_controller.rb) #### `DELETE /api/v1/accounts/:account_id/sub_accounts/:id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/sub_accounts/:id` Cannot delete an account with active courses or active sub\_accounts. Cannot delete a root\_account Returns an [Account](/services/canvas/resources/accounts_-lti#account) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Accounts (LTI) API for accessing account data using an LTI dev key. Allows a tool to get account information via LTI Advantage authorization scheme, which does not require a user session like normal developer keys do. Requires the account lookup scope on the LTI key. #### An Account object looks like: ```js { // the ID of the Account object "id": 2, // The display name of the account "name": "Canvas Account", // The UUID of the account "uuid": "WvAHhY5FINzq5IyRIJybGeiXyFkG3SqHUPb7jZY5", // The account's parent ID, or null if this is the root account "parent_account_id": 1, // The ID of the root account, or null if this is the root account "root_account_id": 1, // The state of the account. Can be 'active' or 'deleted'. "workflow_state": "active" } ``` ## [Get account](#method.lti/account_lookup.show) [Lti::AccountLookupController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/account_lookup_controller.rb) #### `GET /api/lti/accounts/:account_id` **Scope:** `url:GET|/api/lti/accounts/:account_id` Retrieve information on an individual account, given by local or global ID. Returns an [Account](#account) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Admins Manage account role assignments #### An Admin object looks like: ```js { // The unique identifier for the account role/user assignment. "id": 1023, // The account role assigned. This can be 'AccountAdmin' or a user-defined role // created by the Roles API. "role": "AccountAdmin", // The user the role is assigned to. See the Users API for details. "user": null, // The status of the account role/user assignment. "workflow_state": "deleted" } ``` ## [List account admins](#method.admins.index) [AdminsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/admins_controller.rb) #### `GET /api/v1/accounts/:account_id/admins` **Scope:** `url:GET|/api/v1/accounts/:account_id/admins` A paginated list of the admins in the account #### Request Parameters: | Parameter | Type | Description | | ----------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- | | `user_id[]` | `[Integer]` | Scope the results to those with user IDs equal to any of the IDs specified here. | | `search_term` | `string` | The partial name or full ID of the admins to match and return in theresults list. Must be at least 2 characters. | | `include_deleted` | `boolean` | When set to true, returns admins who have been deleted | Returns a list of [Admin](#admin) objects. ## [Make an account admin](#method.admins.create) [AdminsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/admins_controller.rb) #### `POST /api/v1/accounts/:account_id/admins` **Scope:** `url:POST|/api/v1/accounts/:account_id/admins` Flag an existing user as an admin within the account. #### Request Parameters: | Parameter | Type | Description | | ------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | Required `integer` | The id of the user to promote. | | `role` | `string` | \[DEPRECATED] The user's admin relationship with the account will becreated with the given role. Defaults to 'AccountAdmin'. | | `role_id` | `integer` | The user's admin relationship with the account will be created with the given role. Defaults to the built-in role for 'AccountAdmin'. | | `send_confirmation` | `boolean` | Send a notification email tothe new admin if true. Default is true. | Returns an [Admin](#admin) object. ## [Remove account admin](#method.admins.destroy) [AdminsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/admins_controller.rb) #### `DELETE /api/v1/accounts/:account_id/admins/:user_id` **Scope:** `url:DELETE|/api/v1/accounts/:account_id/admins/:user_id` Remove the rights associated with an account admin role from a user. #### Request Parameters: | Parameter | Type | Description | | --------- | ------------------ | ------------------------------------------------------------------------------- | | `role` | `string` | \[DEPRECATED] Account role to remove from the user. | | `role_id` | Required `integer` | The id of the role representing the user's admin relationship with the account. | Returns an [Admin](#admin) object. ## [List my admin roles](#method.admins.self_roles) [AdminsController#self\_roles](https://github.com/instructure/canvas-lms/blob/master/app/controllers/admins_controller.rb) #### `GET /api/v1/accounts/:account_id/admins/self` **Scope:** `url:GET|/api/v1/accounts/:account_id/admins/self` A paginated list of the current user's roles in the account. The results are the same as those returned by the [List account admins](#method.admins.index) endpoint with +user\_id+ set to +self+, except the "Admins - Add / Remove" permission is not required. Returns a list of [Admin](#admin) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # AI Conversations API for managing conversations with AI Experiences. ## [Show conversation](#method.ai_conversations.show) [AiConversationsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id` Get a specific conversation by ID (for teachers viewing student conversations) ## [Get active conversation](#method.ai_conversations.active_conversation) [AiConversationsController#active\_conversation](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations` Get the active conversation for the current user and AI experience ## [Create AI conversation](#method.ai_conversations.create) [AiConversationsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations` Initialize a new conversation with the AI experience ## [Post message to conversation](#method.ai_conversations.post_message) [AiConversationsController#post\_message](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages` Send a message to an existing conversation and get the AI response #### Request Parameters: | Parameter | Type | Description | | --------- | ----------------- | ------------------------------------ | | `message` | Required `string` | The user's message to send to the AI | ## [Delete AI conversation](#method.ai_conversations.destroy) [AiConversationsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `DELETE /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id` End the current conversation session ## [Get conversation evaluation](#method.ai_conversations.evaluation) [AiConversationsController#evaluation](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/evaluation` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/evaluation` Fetch the latest stored evaluation for a conversation from the llm-conversation service. Reads only — does not run the LLM and is not rate-limited. `evaluation` is null when none has been generated yet (llma returns 200 + null, never 404, so this is distinguishable from an outage). `stale` is true when the AI experience was edited after the stored evaluation was generated. ## [Generate conversation evaluation](#method.ai_conversations.create_evaluation) [AiConversationsController#create\_evaluation](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/evaluation` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/evaluation` Run the LLM to (re)generate an evaluation for a conversation and persist it in the llm-conversation service. Rate-limited. Also the Reset path — a fresh run replaces any prior stored evaluation. ## [Create feedback on a conversation message](#method.ai_conversations.create_feedback) [AiConversationsController#create\_feedback](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages/:message_id/feedback` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages/:message_id/feedback` Submit a like or dislike vote on an AI-generated message. Ownership: load\_conversation gates this action — only the conversation owner or a course manager reaches here. Sub-resource (message\_id within the conversation) scoping is delegated to llma. #### Request Parameters: | Parameter | Type | Description | | ------------------ | ----------------- | ----------------------------- | | `vote` | Required `string` | "liked" or "disliked" | | `message_id` | Required `string` | llm-conversation message UUID | | `feedback_message` | `string` | optional text for dislike | ## [Delete feedback on a conversation message](#method.ai_conversations.delete_feedback) [AiConversationsController#delete\_feedback](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_conversations_controller.rb) #### `DELETE /api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages/:message_id/feedback/:feedback_id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/ai_experiences/:ai_experience_id/conversations/:id/messages/:message_id/feedback/:feedback_id` Remove a previously submitted vote (toggling off like/dislike). Ownership: load\_conversation gates this action — only the conversation owner or a course manager reaches here. Sub-resource (message\_id, feedback\_id within the conversation) scoping is delegated to llma. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # AI Experiences API for creating, accessing and updating AI Experiences. AI Experiences are used to create interactive AI-powered learning scenarios within courses. #### An AiExperience object looks like: ```js // An AI Experience for interactive learning { // The ID of the AI experience "id": 234, // The title for the AI experience "title": "Customer Service Simulation", // The description of the AI experience "description": "Practice customer service skills in a simulated environment", // The AI facts for the experience (optional) "facts": "You are a customer service representative...", // The learning objectives for this experience "learning_objective": "Students will practice active listening and problem-solving", // The pedagogical guidance for the experience "pedagogical_guidance": "A customer is calling about a billing issue", // The current published state of the AI experience "workflow_state": "published", // The course this experience belongs to "course_id": 1578941 } ``` ## [List AI experiences](#method.ai_experiences.index) [AiExperiencesController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences` Retrieve the paginated list of AI experiences for a course #### Request Parameters: | Parameter | Type | Description | | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `workflow_state` | `string` | Only return experiences with the specified workflow state.Allowed values: published, unpublished, deleted | Returns a list of [AiExperience](#aiexperience) objects. ## [Show an AI experience](#method.ai_experiences.show) [AiExperiencesController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:id` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id` Retrieve an AI experience by ID Returns an [AiExperience](#aiexperience) object. ## [Show new AI experience form](#method.ai_experiences.new) [AiExperiencesController#new](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/new` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/new` Display the form for creating a new AI experience ## [Show edit AI experience form](#method.ai_experiences.edit) [AiExperiencesController#edit](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:id/edit` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id/edit` Display the form for editing an existing AI experience ## [Create an AI experience](#method.ai_experiences.create) [AiExperiencesController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `POST /api/v1/courses/:course_id/ai_experiences` **Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences` Create a new AI experience for the specified course #### Request Parameters: | Parameter | Type | Description | | ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | `title` | Required `string` | The title of the AI experience. | | `description` | `string` | The description of the AI experience. | | `facts` | `string` | The AI facts for the experience. | | `learning_objective` | Required `string` | The learning objectives for this experience. | | `pedagogical_guidance` | Required `string` | The pedagogical guidance for the experience. | | `workflow_state` | `string` | The initial state of the experience. Defaults to 'unpublished'.Allowed values: published, unpublished | Returns an [AiExperience](#aiexperience) object. ## [Update an AI experience](#method.ai_experiences.update) [AiExperiencesController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `PUT /api/v1/courses/:course_id/ai_experiences/:id` **Scope:** `url:PUT|/api/v1/courses/:course_id/ai_experiences/:id` Update an existing AI experience #### Request Parameters: | Parameter | Type | Description | | ---------------------- | ----------------- | ----------------------------------------------------------------------------- | | `title` | `string` | The title of the AI experience. | | `description` | `string` | The description of the AI experience. | | `facts` | `string` | The AI facts for the experience. | | `learning_objective` | Required `string` | The learning objectives for this experience. | | `pedagogical_guidance` | Required `string` | The pedagogical guidance for the experience. | | `workflow_state` | `string` | The state of the experience.Allowed values: published, unpublished | Returns an [AiExperience](#aiexperience) object. ## [Delete an AI experience](#method.ai_experiences.destroy) [AiExperiencesController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `DELETE /api/v1/courses/:course_id/ai_experiences/:id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/ai_experiences/:id` Delete an AI experience (soft delete - marks as deleted) Returns an [AiExperience](#aiexperience) object. ## [List student AI conversations](#method.ai_experiences.ai_conversations_index) [AiExperiencesController#ai\_conversations\_index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:id/ai_conversations` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id/ai_conversations` Retrieve the latest AI conversation for each student in the course for this AI experience. Only available to teachers and course managers. ## [Show student AI conversation](#method.ai_experiences.ai_conversation_show) [AiExperiencesController#ai\_conversation\_show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb) #### `GET /api/v1/courses/:course_id/ai_experiences/:id/ai_conversations/:conversation_id` **Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id/ai_conversations/:conversation_id` Retrieve a specific student's AI conversation with full message history. Only available to teachers and course managers. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Analytics API for retrieving the data exposed in Canvas Analytics ## [Get department-level participation data](#method.analytics_api.department_participation) #### `GET /api/v1/accounts/:account_id/analytics/terms/:term_id/activity` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/activity` #### `GET /api/v1/accounts/:account_id/analytics/current/activity` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/current/activity` #### `GET /api/v1/accounts/:account_id/analytics/completed/activity` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/completed/activity` Returns page view hits summed across all courses in the department. Two groupings of these counts are returned; one by day (+by\_date+), the other by category (+by\_category+). The possible categories are announcements, assignments, collaborations, conferences, discussions, files, general, grades, groups, modules, other, pages, and quizzes. This and the other department-level endpoints have three variations which all return the same style of data but for different subsets of courses. All share the prefix /api/v1/accounts/\/analytics. The possible suffixes are: * /current: includes all available courses in the default term * /completed: includes all concluded courses in the default term * /terms/\: includes all available or concluded courses in the given term. Courses not yet offered or which have been deleted are never included. /current and /completed are intended for use when the account has only one term. /terms/\ is intended for use when the account has multiple terms. The action follows the suffix. #### Example Request: ```bash curl https:///api/v1/accounts//analytics/current/activity \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/completed/activity \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/terms//activity \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "by_date": { "2012-01-24": 1240, "2012-01-27": 912, }, "by_category": { "announcements": 54, "assignments": 256, "collaborations": 18, "conferences": 26, "discussions": 354, "files": 132, "general": 59, "grades": 177, "groups": 132, "modules": 71, "other": 412, "pages": 105, "quizzes": 356 }, } ``` ## [Get department-level grade data](#method.analytics_api.department_grades) #### `GET /api/v1/accounts/:account_id/analytics/terms/:term_id/grades` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/grades` #### `GET /api/v1/accounts/:account_id/analytics/current/grades` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/current/grades` #### `GET /api/v1/accounts/:account_id/analytics/completed/grades` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/completed/grades` Returns the distribution of grades for students in courses in the department. Each data point is one student's current grade in one course; if a student is in multiple courses, he contributes one value per course, but if he's enrolled multiple times in the same course (e.g. a lecture section and a lab section), he only constributes on value for that course. Grades are binned to the nearest integer score; anomalous grades outside the 0 to 100 range are ignored. The raw counts are returned, not yet normalized by the total count. Shares the same variations on endpoint as the participation data. #### Example Request: ```bash curl https:///api/v1/accounts//analytics/current/grades \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/completed/grades \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/terms//grades \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "0": 95, "1": 1, "2": 0, "3": 0, ... "93": 125, "94": 110, "95": 142, "96": 157, "97": 116, "98": 85, "99": 63, "100": 190 } ``` ## [Get department-level statistics](#method.analytics_api.department_statistics) #### `GET /api/v1/accounts/:account_id/analytics/terms/:term_id/statistics` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/statistics` #### `GET /api/v1/accounts/:account_id/analytics/current/statistics` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/current/statistics` #### `GET /api/v1/accounts/:account_id/analytics/completed/statistics` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/completed/statistics` Returns numeric statistics about the department and term (or filter). Shares the same variations on endpoint as the participation data. #### Example Request: ```bash curl https:///api/v1/accounts//analytics/current/statistics \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/completed/statistics \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/terms//statistics \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "courses": 27, "subaccounts": 3, "teachers": 36, "students": 418, "discussion_topics": 77, "media_objects": 219, "attachments": 1268, "assignments": 290, } ``` ## [Get department-level statistics, broken down by subaccount](#method.analytics_api.department_statistics_by_subaccount) #### `GET /api/v1/accounts/:account_id/analytics/terms/:term_id/statistics_by_subaccount` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/statistics_by_subaccount` #### `GET /api/v1/accounts/:account_id/analytics/current/statistics_by_subaccount` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/current/statistics_by_subaccount` #### `GET /api/v1/accounts/:account_id/analytics/completed/statistics_by_subaccount` **Scope:** `url:GET|/api/v1/accounts/:account_id/analytics/completed/statistics_by_subaccount` Returns numeric statistics about the department subaccounts and term (or filter). Shares the same variations on endpoint as the participation data. #### Example Request: ```bash curl https:///api/v1/accounts//analytics/current/statistics_by_subaccount \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/completed/statistics_by_subaccount \ -H 'Authorization: Bearer ' curl https:///api/v1/accounts//analytics/terms//statistics_by_subaccount \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js {"accounts": [ { "name": "some string", "id": 188, "courses": 27, "teachers": 36, "students": 418, "discussion_topics": 77, "media_objects": 219, "attachments": 1268, "assignments": 290, } ]} ``` ## [Get course-level participation data](#method.analytics_api.course_participation) #### `GET /api/v1/courses/:course_id/analytics/activity` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/activity` Returns page view hits and participation numbers grouped by day through the entire history of the course. Page views is returned as a hash, where the hash keys are dates in the format "YYYY-MM-DD". The page\_views result set includes page views broken out by access category. Participations is returned as an array of dates in the format "YYYY-MM-DD". #### Example Request: ```bash curl https:///api/v1/courses//analytics/activity \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [ { "date": "2012-01-24", "participations": 3, "views": 10 } ] ``` ## [Get course-level assignment data](#method.analytics_api.course_assignments) #### `GET /api/v1/courses/:course_id/analytics/assignments` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/assignments` Returns a list of assignments for the course sorted by due date. For each assignment returns basic assignment information, the grade breakdown, and a breakdown of on-time/late status of homework submissions. #### Request Parameters: | Parameter | Type | Description | | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `async` | `boolean` | If async is true, then the course\_assignments call can happen asynch-ronously and MAY return a response containing a progress\_url key insteadof an assignments array. If it does, then it is the caller'sresponsibility to poll the API again to see if the progress is complete.If the data is ready (possibly even on the first async call) then itwill be passed back normally, as documented in the example response. | #### Example Request: ```bash curl https:///api/v1/courses//analytics/assignments \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [ { "assignment_id": 1234, "title": "Assignment 1", "points_possible": 10, "due_at": "2012-01-25T22:00:00-07:00", "unlock_at": "2012-01-20T22:00:00-07:00", "muted": false, "min_score": 2, "max_score": 10, "median": 7, "first_quartile": 4, "third_quartile": 8, "tardiness_breakdown": { "on_time": 0.75, "missing": 0.1, "late": 0.15 } }, { "assignment_id": 1235, "title": "Assignment 2", "points_possible": 15, "due_at": "2012-01-26T22:00:00-07:00", "unlock_at": null, "muted": true, "min_score": 8, "max_score": 8, "median": 8, "first_quartile": 8, "third_quartile": 8, "tardiness_breakdown": { "on_time": 0.65, "missing": 0.12, "late": 0.23 "total": 275 } } ] ``` ## [Get course-level student summary data](#method.analytics_api.course_student_summaries) #### `GET /api/v1/courses/:course_id/analytics/student_summaries` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/student_summaries` Returns a summary of per-user access information for all students in a course. This includes total page views, total participations, and a breakdown of on-time/late status for all homework submissions in the course. Each student's summary also includes the maximum number of page views and participations by any student in the course, which may be useful for some visualizations (since determining maximums client side can be tricky with pagination). #### Request Parameters: | Parameter | Type | Description | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sort_column` | `string` | The order results in which results are returned. Defaults to "name". Allowed values: `name`, `name_descending`, `score`, `score_descending`, `participations`, `participations_descending`, `page_views`, `page_views_descending` | | `student_id` | `string` | If set, returns only the specified student. | #### Example Request: ```bash curl https:///api/v1/courses//analytics/student_summaries \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [ { "id": 2346, "page_views": 351, "page_views_level": "1" "max_page_view": 415, "participations": 1, "participations_level": "3", "max_participations": 10, "tardiness_breakdown": { "total": 5, "on_time": 3, "late": 0, "missing": 2, "floating": 0 } }, { "id": 2345, "page_views": 124, "participations": 15, "tardiness_breakdown": { "total": 5, "on_time": 1, "late": 2, "missing": 3, "floating": 0 } } ] ``` ## [Get user-in-a-course-level participation data](#method.analytics_api.student_in_course_participation) #### `GET /api/v1/courses/:course_id/analytics/users/:student_id/activity` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/activity` Returns page view hits grouped by hour, and participation details through the entire history of the course. `page_views` are returned as a hash, where the keys are iso8601 dates, bucketed by the hour. `participations` are returned as an array of hashes, sorted oldest to newest. #### Example Request: ```bash curl https:///api/v1/courses//analytics/users//activity \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "page_views": { "2012-01-24T13:00:00-00:00": 19, "2012-01-24T14:00:00-00:00": 13, "2012-01-27T09:00:00-00:00": 23 }, "participations": [ { "created_at": "2012-01-21T22:00:00-06:00", "url": "https://canvas.example.com/path/to/canvas", }, { "created_at": "2012-01-27T22:00:00-06:00", "url": "https://canvas.example.com/path/to/canvas", } ] } ``` ## [Get user-in-a-course-level assignment data](#method.analytics_api.student_in_course_assignments) #### `GET /api/v1/courses/:course_id/analytics/users/:student_id/assignments` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/assignments` Returns a list of assignments for the course sorted by due date. For each assignment returns basic assignment information, the grade breakdown (including the student's actual grade), and the basic submission information for the student's submission if it exists. #### Example Request: ```bash curl https:///api/v1/courses//analytics/users//assignments \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [ { "assignment_id": 1234, "title": "Assignment 1", "points_possible": 10, "due_at": "2012-01-25T22:00:00-07:00", "unlock_at": "2012-01-20T22:00:00-07:00", "muted": false, "min_score": 2, "max_score": 10, "median": 7, "first_quartile": 4, "third_quartile": 8, "module_ids": [ 1, 2 ], "submission": { "posted_at": "2012-01-23T20:00:00-07:00", "submitted_at": "2012-01-22T22:00:00-07:00", "score": 10 } }, { "assignment_id": 1235, "title": "Assignment 2", "points_possible": 15, "due_at": "2012-01-26T22:00:00-07:00", "unlock_at": null, "muted": true, "min_score": 8, "max_score": 8, "median": 8, "first_quartile": 8, "third_quartile": 8, "module_ids": [ 1 ], "submission": { "posted_at": null, "submitted_at": "2012-01-22T22:00:00-07:00" } } ] ``` ## [Get user-in-a-course-level messaging data](#method.analytics_api.student_in_course_messaging) #### `GET /api/v1/courses/:course_id/analytics/users/:student_id/communication` **Scope:** `url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/communication` Returns messaging "hits" grouped by day through the entire history of the course. Returns a hash containing the number of instructor-to-student messages, and student-to-instructor messages, where the hash keys are dates in the format "YYYY-MM-DD". Message hits include Conversation messages and comments on homework submissions. #### Example Request: ```bash curl https:///api/v1/courses//analytics/users//communication \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js { "2012-01-24":{ "instructorMessages":1, "studentMessages":2 }, "2012-01-27":{ "studentMessages":1 } } ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Announcement External Feeds External feeds represent RSS feeds that can be attached to a Course or Group, in order to automatically create announcements for each new item in the feed. #### An ExternalFeed object looks like: ```js { // The ID of the feed "id": 5, // The title of the feed, pulled from the feed itself. If the feed hasn't yet // been pulled, a temporary name will be synthesized based on the URL "display_name": "My Blog", // The HTTP/HTTPS URL to the feed "url": "http://example.com/myblog.rss", // If not null, only feed entries whose title contains this string will trigger // new posts in Canvas "header_match": "pattern", // When this external feed was added to Canvas "created_at": "2012-06-01T00:00:00-06:00", // The verbosity setting determines how much of the feed's content is imported // into Canvas as part of the posting. 'link_only' means that only the title and // a link to the item. 'truncate' means that a summary of the first portion of // the item body will be used. 'full' means that the full item body will be // used. "verbosity": "truncate" } ``` ## [List external feeds](#method.external_feeds.index) [ExternalFeedsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/external_feeds_controller.rb) #### `GET /api/v1/courses/:course_id/external_feeds` **Scope:** `url:GET|/api/v1/courses/:course_id/external_feeds` #### `GET /api/v1/groups/:group_id/external_feeds` **Scope:** `url:GET|/api/v1/groups/:group_id/external_feeds` Returns the paginated list of External Feeds this course or group. #### Example Request: ```bash curl https:///api/v1/courses//external_feeds \ -H 'Authorization: Bearer ' ``` Returns a list of [ExternalFeed](#externalfeed) objects. ## [Create an external feed](#method.external_feeds.create) [ExternalFeedsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/external_feeds_controller.rb) #### `POST /api/v1/courses/:course_id/external_feeds` **Scope:** `url:POST|/api/v1/courses/:course_id/external_feeds` #### `POST /api/v1/groups/:group_id/external_feeds` **Scope:** `url:POST|/api/v1/groups/:group_id/external_feeds` Create a new external feed for the course or group. #### Request Parameters: | Parameter | Type | Description | | -------------- | ----------------- | ------------------------------------------------------------------------------------ | | `url` | Required `string` | The url to the external rss or atom feed | | `header_match` | `boolean` | If given, only feed entries that contain this string in their title will be imported | | `verbosity` | `string` | Defaults to "full" Allowed values: `full`, `truncate`, `link_only` | #### Example Request: ```bash curl https:///api/v1/courses//external_feeds \ -F url='http://example.com/rss.xml' \ -F header_match='news flash!' \ -F verbosity='full' \ -H 'Authorization: Bearer ' ``` Returns an [ExternalFeed](#externalfeed) object. ## [Delete an external feed](#method.external_feeds.destroy) [ExternalFeedsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/external_feeds_controller.rb) #### `DELETE /api/v1/courses/:course_id/external_feeds/:external_feed_id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/external_feeds/:external_feed_id` #### `DELETE /api/v1/groups/:group_id/external_feeds/:external_feed_id` **Scope:** `url:DELETE|/api/v1/groups/:group_id/external_feeds/:external_feed_id` Deletes the external feed. #### Example Request: ```bash curl -X DELETE https:///api/v1/courses//external_feeds/ \ -H 'Authorization: Bearer ' ``` Returns an [ExternalFeed](#externalfeed) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Announcements API for retrieving announcements. This API is Announcement-specific. See also the Discussion Topics API, which operates on Announcements also. ## [List announcements](#method.announcements_api.index) [AnnouncementsApiController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/announcements_api_controller.rb) #### `GET /api/v1/announcements` **Scope:** `url:GET|/api/v1/announcements` Returns the paginated list of announcements for the given courses and date range. Note that a +context\_code+ field is added to the responses so you can tell which course each announcement belongs to. #### Request Parameters: | Parameter | Type | Description | | ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `context_codes[]` | Required `string` | List of context\_codes to retrieve announcements for (for example, +course\_123+). Only coursesare presently supported. The call will fail unless the caller has View Announcements permissionin all listed courses. | | `start_date` | `Date` | Only return announcements posted since the start\_date (inclusive).Defaults to 14 days ago. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. | | `end_date` | `Date` | Only return announcements posted before the end\_date (inclusive).Defaults to 28 days from start\_date. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.Announcements scheduled for future posting will only be returned to course administrators. | | `available_after` | `Date` | Only return announcements having locked\_at nil or after available\_after (exclusive).The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.Effective only for students (who don't have moderate forum right). | | `active_only` | `boolean` | Only return active announcements that have been published.Applies only to requesting users that have permission to viewunpublished items.Defaults to false for users with access to view unpublished items,otherwise true and unmodifiable. | | `latest_only` | `boolean` | Only return the latest announcement for each associated context.The response will include at most one announcement for eachspecified context in the context\_codes\[] parameter.Defaults to false. | | `include` | `array` | Optional list of resources to include with the response. May includea string of the name of the resource. Possible values are:"sections", "sections\_user\_count"if "sections" is passed, includes the course sections that are associatedwith the topic, if the topic is specific to certain sections of the course.If "sections\_user\_count" is passed, then:(a) If sections were asked for and the topic is specific to certaincourse sections sections, includes the number of users in eachsection. (as part of the section json asked for above)(b) Else, includes at the root level the total number of users in thetopic's context (group or course) that the topic applies to. | #### Example Request: ```bash curl https:///api/v1/announcements?context_codes[]=course_1&context_codes[]=course_2 \ -H 'Authorization: Bearer ' ``` #### Example Response: ```js [{ "id": 1, "title": "Hear ye", "message": "Henceforth, all assignments must be...", "posted_at": "2017-01-31T22:00:00Z", "delayed_post_at": null, "context_code": "course_2", ... }] ``` Returns a list of [DiscussionTopic](/services/canvas/resources/discussion_topics#discussiontopic) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # API Token Scopes {% hint style="warning" %} BETA: This API resource is not finalized, and there could be breaking changes before its final release. {% endhint %} API for retrieving API scopes #### A Scope object looks like: ```js { // The resource the scope is associated with "resource": "courses", // The localized resource name "resource_name": "Courses", // The controller the scope is associated to "controller": "courses", // The controller action the scope is associated to "action": "index", // The HTTP verb for the scope "verb": "GET", // The identifier for the scope "scope": "url:GET|/api/v1/courses" } ``` ## [List scopes](#method.scopes_api.index) [ScopesApiController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/scopes_api_controller.rb) {% hint style="warning" %} BETA: This API endpoint is not finalized, and there could be breaking changes before its final release. {% endhint %} #### `GET /api/v1/accounts/:account_id/scopes` **Scope:** `url:GET|/api/v1/accounts/:account_id/scopes` A list of scopes that can be applied to developer keys and access tokens. #### Request Parameters: | Parameter | Type | Description | | ---------- | -------- | ----------------------------------------------------------------------------------------------------- | | `group_by` | `string` | The attribute to group the scopes by. By default no grouping is done. Allowed values: `resource_name` | Returns a list of [Scope](#scope) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Appointment Groups API for creating, accessing and updating appointment groups. Appointment groups provide a way of creating a bundle of time slots that users can sign up for (e.g. "Office Hours" or "Meet with professor about Final Project"). Both time slots and reservations of time slots are stored as Calendar Events. #### An Appointment object looks like: ```js // Date and time for an appointment { // The appointment identifier. "id": 987, // Start time for the appointment "start_at": "2012-07-20T15:00:00-06:00", // End time for the appointment "end_at": "2012-07-20T15:00:00-06:00" } ``` #### An AppointmentGroup object looks like: ```js { // The ID of the appointment group "id": 543, // The title of the appointment group "title": "Final Presentation", // The start of the first time slot in the appointment group "start_at": "2012-07-20T15:00:00-06:00", // The end of the last time slot in the appointment group "end_at": "2012-07-20T17:00:00-06:00", // The text description of the appointment group "description": "Es muy importante", // The location name of the appointment group "location_name": "El Tigre Chino's office", // The address of the appointment group's location "location_address": "Room 234", // The number of participant who have reserved slots (see include[] argument) "participant_count": 2, // The start and end times of slots reserved by the current user as well as the // id of the calendar event for the reservation (see include[] argument) "reserved_times": [{"id":987,"start_at":"2012-07-20T15:00:00-06:00","end_at":"2012-07-20T15:00:00-06:00"}], // Boolean indicating whether observer users should be able to sign-up for an // appointment "allow_observer_signup": false, // The context codes (i.e. courses) this appointment group belongs to. Only // people in these courses will be eligible to sign up. "context_codes": ["course_123"], // The sub-context codes (i.e. course sections and group categories) this // appointment group is restricted to "sub_context_codes": [course_section_234], // Current state of the appointment group ('pending', 'active' or 'deleted'). // 'pending' indicates that it has not been published yet and is invisible to // participants. "workflow_state": "active", // Boolean indicating whether the current user needs to sign up for this // appointment group (i.e. it's reservable and the // min_appointments_per_participant limit has not been met by this user). "requiring_action": true, // Number of time slots in this appointment group "appointments_count": 2, // Calendar Events representing the time slots (see include[] argument) Refer to // the Calendar Events API for more information "appointments": [], // Newly created time slots (same format as appointments above). Only returned // in Create/Update responses where new time slots have been added "new_appointments": [], // Maximum number of time slots a user may register for, or null if no limit "max_appointments_per_participant": 1, // Minimum number of time slots a user must register for. If not set, users do // not need to sign up for any time slots "min_appointments_per_participant": 1, // Maximum number of participants that may register for each time slot, or null // if no limit "participants_per_appointment": 1, // 'private' means participants cannot see who has signed up for a particular // time slot, 'protected' means that they can "participant_visibility": "private", // Indicates how participants sign up for the appointment group, either as // individuals ('User') or in student groups ('Group'). Related to // sub_context_codes (i.e. 'Group' signups always have a single group category) "participant_type": "User", // URL for this appointment group (to update, delete, etc.) "url": "https://example.com/api/v1/appointment_groups/543", // URL for a user to view this appointment group "html_url": "http://example.com/appointment_groups/1", // When the appointment group was created "created_at": "2012-07-13T10:55:20-06:00", // When the appointment group was last updated "updated_at": "2012-07-13T10:55:20-06:00" } ``` ## [List appointment groups](#method.appointment_groups.index) [AppointmentGroupsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups` **Scope:** `url:GET|/api/v1/appointment_groups` Retrieve the paginated list of appointment groups that can be reserved or managed by the current user. #### Request Parameters: | Parameter | Type | Description | | --------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `scope` | `string` | Defaults to "reservable" Allowed values: `reservable`, `manageable` | | `context_codes[]` | `string` | Array of context codes used to limit returned results. | | `include_past_appointments` | `boolean` | Defaults to false. If true, includes past appointment groups | | `include[]` | `string` | Array of additional information to include."appointments":: calendar event time slots for this appointment group"child\_events":: reservations of those time slots"participant\_count":: number of reservations"reserved\_times":: the event id, start time and end time of reservationsthe current user has made)"all\_context\_codes":: all context codes associated with this appointment group Allowed values: appointments, child\_events, participant\_count, reserved\_times, all\_context\_codes | ## [Create an appointment group](#method.appointment_groups.create) [AppointmentGroupsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `POST /api/v1/appointment_groups` **Scope:** `url:POST|/api/v1/appointment_groups` Create and return a new appointment group. If new\_appointments are specified, the response will return a new\_appointments array (same format as appointments array, see "List appointment groups" action) #### Request Parameters: | Parameter | Type | Description | | ----------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `appointment_group[context_codes][]` | Required `string` | Array of context codes (courses, e.g. course\_1) this group should belinked to (1 or more). Users in the course(s) with appropriate permissionswill be able to sign up for this appointment group. | | `appointment_group[sub_context_codes][]` | `string` | Array of sub context codes (course sections or a single group category)this group should be linked to. Used to limit the appointment group toparticular sections. If a group category is specified, students will signup in groups and the participant\_type will be "Group" instead of "User". | | `appointment_group[title]` | Required `string` | Short title for the appointment group. | | `appointment_group[description]` | `string` | Longer text description of the appointment group. | | `appointment_group[location_name]` | `string` | Location name of the appointment group. | | `appointment_group[location_address]` | `string` | Location address. | | `appointment_group[publish]` | `boolean` | Indicates whether this appointment group should be published (i.e. madeavailable for signup). Once published, an appointment group cannot beunpublished. Defaults to false. | | `appointment_group[participants_per_appointment]` | `integer` | Maximum number of participants that may register for each time slot.Defaults to null (no limit). | | `appointment_group[min_appointments_per_participant]` | `integer` | Minimum number of time slots a user must register for. If not set, usersdo not need to sign up for any time slots. | | `appointment_group[max_appointments_per_participant]` | `integer` | Maximum number of time slots a user may register for. | | `appointment_group[new_appointments][X][]` | `string` | Nested array of start time/end time pairs indicating time slots for thisappointment group. Refer to the example request. | | `appointment_group[participant_visibility]` | `string` | "private":: participants cannot see who has signed up for a particulartime slot"protected":: participants can see who has signed up. Defaults to"private". Allowed values: private, protected | | `appointment_group[allow_observer_signup]` | `boolean` | Whether observer users can sign-up for an appointment. Defaults to false. | #### Example Request: ```bash curl 'https:///api/v1/appointment_groups.json' \ -X POST \ -F 'appointment_group[context_codes][]=course_123' \ -F 'appointment_group[sub_context_codes][]=course_section_234' \ -F 'appointment_group[title]=Final Presentation' \ -F 'appointment_group[participants_per_appointment]=1' \ -F 'appointment_group[min_appointments_per_participant]=1' \ -F 'appointment_group[max_appointments_per_participant]=1' \ -F 'appointment_group[new_appointments][0][]=2012-07-19T21:00:00Z' \ -F 'appointment_group[new_appointments][0][]=2012-07-19T22:00:00Z' \ -F 'appointment_group[new_appointments][1][]=2012-07-19T22:00:00Z' \ -F 'appointment_group[new_appointments][1][]=2012-07-19T23:00:00Z' \ -H "Authorization: Bearer " ``` ## [Get a single appointment group](#method.appointment_groups.show) [AppointmentGroupsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups/:id` **Scope:** `url:GET|/api/v1/appointment_groups/:id` Returns information for a single appointment group #### Request Parameters: | Parameter | Type | Description | | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Array of additional information to include. See include\[] argument of"List appointment groups" action."child\_events":: reservations of time slots time slots"appointments":: will always be returned"all\_context\_codes":: all context codes associated with this appointment group Allowed values: child\_events, appointments, all\_context\_codes | ## [Update an appointment group](#method.appointment_groups.update) [AppointmentGroupsController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `PUT /api/v1/appointment_groups/:id` **Scope:** `url:PUT|/api/v1/appointment_groups/:id` Update and return an appointment group. If new\_appointments are specified, the response will return a new\_appointments array (same format as appointments array, see "List appointment groups" action). #### Request Parameters: | Parameter | Type | Description | | ----------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `appointment_group[context_codes][]` | Required `string` | Array of context codes (courses, e.g. course\_1) this group should belinked to (1 or more). Users in the course(s) with appropriate permissionswill be able to sign up for this appointment group. | | `appointment_group[sub_context_codes][]` | `string` | Array of sub context codes (course sections or a single group category)this group should be linked to. Used to limit the appointment group toparticular sections. If a group category is specified, students will signup in groups and the participant\_type will be "Group" instead of "User". | | `appointment_group[title]` | `string` | Short title for the appointment group. | | `appointment_group[description]` | `string` | Longer text description of the appointment group. | | `appointment_group[location_name]` | `string` | Location name of the appointment group. | | `appointment_group[location_address]` | `string` | Location address. | | `appointment_group[publish]` | `boolean` | Indicates whether this appointment group should be published (i.e. madeavailable for signup). Once published, an appointment group cannot beunpublished. Defaults to false. | | `appointment_group[participants_per_appointment]` | `integer` | Maximum number of participants that may register for each time slot.Defaults to null (no limit). | | `appointment_group[min_appointments_per_participant]` | `integer` | Minimum number of time slots a user must register for. If not set, usersdo not need to sign up for any time slots. | | `appointment_group[max_appointments_per_participant]` | `integer` | Maximum number of time slots a user may register for. | | `appointment_group[new_appointments][X][]` | `string` | Nested array of start time/end time pairs indicating time slots for thisappointment group. Refer to the example request. | | `appointment_group[participant_visibility]` | `string` | "private":: participants cannot see who has signed up for a particulartime slot"protected":: participants can see who has signed up. Defaults to "private". Allowed values: private, protected | | `appointment_group[allow_observer_signup]` | `boolean` | Whether observer users can sign-up for an appointment. | #### Example Request: ```bash curl 'https:///api/v1/appointment_groups/543.json' \ -X PUT \ -F 'appointment_group[publish]=1' \ -H "Authorization: Bearer " ``` ## [Delete an appointment group](#method.appointment_groups.destroy) [AppointmentGroupsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `DELETE /api/v1/appointment_groups/:id` **Scope:** `url:DELETE|/api/v1/appointment_groups/:id` Delete an appointment group (and associated time slots and reservations) and return the deleted group #### Request Parameters: | Parameter | Type | Description | | --------------- | -------- | ---------------------------------------------------- | | `cancel_reason` | `string` | Reason for deleting/canceling the appointment group. | #### Example Request: ```bash curl 'https:///api/v1/appointment_groups/543.json' \ -X DELETE \ -F 'cancel_reason=El Tigre Chino got fired' \ -H "Authorization: Bearer " ``` ## [List user participants](#method.appointment_groups.users) [AppointmentGroupsController#users](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups/:id/users` **Scope:** `url:GET|/api/v1/appointment_groups/:id/users` A paginated list of users that are (or may be) participating in this appointment group. Refer to the Users API for the response fields. Returns no results for appointment groups with the "Group" participant\_type. #### Request Parameters: | Parameter | Type | Description | | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `registration_status` | `string` | Limits results to the a given participation status, defaults to "all" Allowed values: `all`, `registered`, `registered` | ## [List student group participants](#method.appointment_groups.groups) [AppointmentGroupsController#groups](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups/:id/groups` **Scope:** `url:GET|/api/v1/appointment_groups/:id/groups` A paginated list of student groups that are (or may be) participating in this appointment group. Refer to the Groups API for the response fields. Returns no results for appointment groups with the "User" participant\_type. #### Request Parameters: | Parameter | Type | Description | | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `registration_status` | `string` | Limits results to the a given participation status, defaults to "all" Allowed values: `all`, `registered`, `registered` | ## [Get next appointment](#method.appointment_groups.next_appointment) [AppointmentGroupsController#next\_appointment](https://github.com/instructure/canvas-lms/blob/master/app/controllers/appointment_groups_controller.rb) #### `GET /api/v1/appointment_groups/next_appointment` **Scope:** `url:GET|/api/v1/appointment_groups/next_appointment` Return the next appointment available to sign up for. The appointment is returned in a one-element array. If no future appointments are available, an empty array is returned. #### Request Parameters: | Parameter | Type | Description | | ------------------------- | -------- | -------------------------------------------- | | `appointment_group_ids[]` | `string` | List of ids of appointment groups to search. | Returns a list of [CalendarEvent](/services/canvas/resources/calendar_events#calendarevent) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Assessment Question Banks #### An AssessmentQuestionBank object looks like: ```js { // The ID of the assessment question bank. "id": 1, // The ID of the context (course or account) the question bank belongs to. "context_id": 2, // The type of context (Course or Account). "context_type": "Course", // The title of the question bank. "title": "Chapter 1 Questions", // The workflow state of the question bank. "workflow_state": "active", // The number of questions in the bank. "assessment_question_count": 10, // The combined context type and ID. "context_code": "course_2", // The date and time the question bank was created. "created_at": "2013-01-01T00:00:00Z", // The date and time the question bank was last updated. "updated_at": "2013-01-01T00:00:00Z" } ``` #### An AssessmentQuestion object looks like: ```js { // The ID of the assessment question. "id": 1, // The order of the question. "position": 1, // The ID of the question bank this question belongs to. "assessment_question_bank_id": 3, // The date and time when the assessment question was created. "created_at": "2013-01-23T23:59:00-07:00", // The name of the question. "question_name": "Prime Number Identification", // The type of the question. "question_type": "multiple_choice_question", // The text of the question. "question_text": "Which of the following is NOT a prime number?", // The maximum amount of points possible received for getting this question // correct. "points_possible": 5, // The comments to display if the student answers the question correctly. "correct_comments": "That's correct!", // The comments to display if the student answers incorrectly. "incorrect_comments": "Unfortunately, that IS a prime number.", // The comments to display regardless of how the student answered. "neutral_comments": "Goldbach's conjecture proposes that every even integer greater than 2 can be expressed as the sum of two prime numbers.", // The HTML version of the comments to display if the student answers the // question correctly. "correct_comments_html": "That's correct!", // The HTML version of the comments to display if the student answers // incorrectly. "incorrect_comments_html": "Unfortunately, that IS a prime number.", // The HTML version of the comments to display regardless of how the student // answered. "neutral_comments_html": "Goldbach's conjecture proposes that every even integer greater than 2 can be expressed as the sum of two prime numbers.", // An array of available answers. Each answer contains id, text, html, comments, // comments_html, and weight properties. "answers": null, // Variables for calculated questions. Null for other question types. "variables": null, // Formulas for calculated questions. Null for other question types. "formulas": null, // The tolerance for numerical answers. Null for non-numerical question types. "answer_tolerance": null, // The number of decimal places for formula results. Null for non-calculated // question types. "formula_decimal_places": null, // Matching pairs for matching questions. Null for other question types. "matches": null, // Incorrect match options for matching questions. Null for other question // types. "matching_answer_incorrect_matches": null } ``` ## [List question banks](#method.assessment_question_banks.index) [AssessmentQuestionBanksController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assessment_question_banks_controller.rb) #### `GET /api/v1/question_banks` **Scope:** `url:GET|/api/v1/question_banks` Returns the paginated list of question banks for a given context. #### Request Parameters: | Parameter | Type | Description | | ------------------------ | ------------------ | ---------------------------------------------------------------------------------------------- | | `context_type` | Required `string` | The type of context. Must be either "Course" or "Account". Allowed values: `Course`, `Account` | | `context_id` | Required `integer` | The id of the context. | | `include_question_count` | `boolean` | Whether to include the number of questions in each bank. | #### Example Request: ```bash curl 'https:///api/v1/question_banks?context_type=Course&context_id=1' \ -H 'Authorization: Bearer ' ``` Returns a list of [AssessmentQuestionBank](#assessmentquestionbank) objects. ## [Get a single question bank](#method.assessment_question_banks.show) [AssessmentQuestionBanksController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assessment_question_banks_controller.rb) #### `GET /api/v1/question_banks/:id` **Scope:** `url:GET|/api/v1/question_banks/:id` Returns the question bank with the given id #### Request Parameters: | Parameter | Type | Description | | ------------------------ | ------------------ | ------------------------------------------------------- | | `id` | Required `integer` | The question bank unique identifier. | | `include_question_count` | `boolean` | Whether to include the number of questions in the bank. | Returns an [AssessmentQuestionBank](#assessmentquestionbank) object. ## [List assessment questions for a question bank](#method.assessment_question_banks.questions) [AssessmentQuestionBanksController#questions](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assessment_question_banks_controller.rb) #### `GET /api/v1/question_banks/:id/questions` **Scope:** `url:GET|/api/v1/question_banks/:id/questions` Returns the paginated list of assessment questions in this bank. #### Request Parameters: | Parameter | Type | Description | | --------- | ------------------ | ------------------------------------ | | `id` | Required `integer` | The question bank unique identifier. | #### Example Request: ```bash curl 'https:///api/v1/question_banks/:id/questions' \ -H 'Authorization: Bearer ' ``` Returns a list of [AssessmentQuestion](#assessmentquestion) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Asset Processor 1EdTech Asset Processor services: Asset Service and Asset Report Service. 1EdTech Asset Processor services: Eula Service and Eula Acceptance Service. ## [Create an Asset Report](#method.lti/ims/asset_processor.create_report) [Lti::Ims::AssetProcessorController#create\_report](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/ims/asset_processor_controller.rb) #### `POST /api/lti/asset_processors/:asset_processor_id/reports` **Scope:** `url:POST|/api/lti/asset_processors/:asset_processor_id/reports` Creates a report for a given Canvas-managed asset (such as a submission attachment). Returns an HTTP 201 (Created) on success. #### Request Parameters: | Parameter | Type | Description | | -------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `assetId` | `string` | The UUID of the asset to which the report applies. Canvas will supplythis to the tool in the the LtiAssetProcessorSubmissionNotice. | | `errorCode` | `string` | A machine-readable code indicating the cause of the failure, for reportswith a processingProgress value of Failed. The following standard errorcodes are available, but tools may use their own (in which case the toolmay provide human-readable information in the comment field):UNSUPPORTED\_ASSET\_TYPE, ASSET\_TOO\_LARGE, ASSET\_TOO\_SMALL,EULA\_NOT\_ACCEPTED, DOWNLOAD\_FAILED | | `indicationAlt` | `string` | Alternate text representing the meaning of the indicationColor for screenreaders or as a tooltip over the indication color. | | `indicationColor` | `string` | A hex (#RRGGBB) color code the tool wishes to use indicating the outcomeof an asset's report. | | `priority` | `integer` | A number from 0 (meaning "good" or "success") to 5 (meaning urgent ortime-critical notable features) indicating the tool's perceived priorityof the report. If a priority is not known or applicable, the tool shoulduse the value 0. | | `processingProgress` | `string` | Indicates the status of the report. Should be one of the following:Processed, Processing, PendingManual, Failed, NotProcessed, NotReady.If an unrecognized value is given, the value will be stored, but willbe treated by Canvas as NotReady. | | `result` | `string` | A short string (16 characters or fewer) that briefly describes thesuccessful result of the processing. This should be provided ifprocessingProgress is Processed, and not provided otherwise. | | `timestamp` | `string` | An ISO8601 date time value with microsecond precision. Reports with newertimestamps for the same asset and report type supersedepreviously submitted reports with older (or equal) timestamps. Likewise,if the timestamp provided is older than the latest timestamp for anexisting report (of same asset and type), the new report will beignored and the endpoint will return an HTTP 409 (Conflict). | | `title` | `string` | A human-readable title for the report, to be displayed to the user. | | `type` | `string` | An opaque value representing the type of report. | | `visibleToOwner` | `boolean` | A boolean value indicates whether the indicator and reportshould be visible to the user who owns the asset being reported on.If no value is provided, the platform should assume a default value of false | #### Example Request: ```bash { "assetId" : "57d463ea-6e5d-45c8-a86f-64f3dd9ef81e", "type": "originality", "timestamp": "2025-01-24T17:56:53.221+00:00", "title": "Originality Report", "result" : "75/100", "indicationColor" : "#EC0000", "indicationAlt" : "High percentage of matched text.", "priority": 5, "processingProgress": "Processed" } ``` ```bash { "assetId" : "57d463ea-6e5d-45c8-a86f-64f3dd9ef81e", "type": "originality", "timestamp": "2025-01-24T17:56:53.221+00:00", "title": "Originality Report", "priority": 0, "errorCode": "UNSUPPORTED_ASSET_TYPE", "processingProgress": "Failed" } ``` #### Example Response: ```js { "assetId" : "57d463ea-6e5d-45c8-a86f-64f3dd9ef81e", "type": "originality", "timestamp": "2025-01-24T17:56:53.221+00:00", "title": "Originality Report", "result" : "75/100", "indicationColor" : "#EC0000", "indicationAlt" : "High percentage of matched text.", "priority": 5, "processingProgress": "Processed" } ``` ## [Update Eula Deployment Configuration](#method.lti/ims/asset_processor_eula.update_tool_eula) [Lti::Ims::AssetProcessorEulaController#update\_tool\_eula](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/ims/asset_processor_eula_controller.rb) #### `PUT /api/lti/asset_processor_eulas/:context_external_tool_id/deployment` **Scope:** `url:PUT|/api/lti/asset_processor_eulas/:context_external_tool_id/deployment` Provides a mechanism by which a platform can enable or disable the requirement for users to accept a EULA within the scope of an entire deployment #### Request Parameters: | Parameter | Type | Description | | -------------- | --------- | ------------------------------------------------------------------------------------ | | `eulaRequired` | `boolean` | A boolean value representing whether or not the EULA is required for the deployment. | #### Example Request: ```bash { "eulaRequired": true, } ``` #### Example Response: ```js { "eulaRequired": true, } ``` ## [Create an Eula Acceptance](#method.lti/ims/asset_processor_eula.create_acceptance) [Lti::Ims::AssetProcessorEulaController#create\_acceptance](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/ims/asset_processor_eula_controller.rb) #### `POST /api/lti/asset_processor_eulas/:context_external_tool_id/user` **Scope:** `url:POST|/api/lti/asset_processor_eulas/:context_external_tool_id/user` The EULA user acceptance service provides a mechanism by which a tool can notify a platform of whether or not a user has accepted a EULA. #### Request Parameters: | Parameter | Type | Description | | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userId` | `string` | The userId represents the user who has accepted or declined the EULA,lti\_id of the Canvas User. | | `accepted` | `boolean` | A boolean value representing whether or not the user has accepted the EULA | | `timestamp` | `string` | The timestamp represents the time at which the user accepted or declined the EULA.This timestamp must be formatted as an ISO 8601 date time. | #### Example Request: ```bash { "userId": "59ed2101-0302-406c-b53f-9705ae1cb357", "accepted": true, "timestamp": "2022-04-16T18:54:36.736+00:00" } ``` #### Example Response: ```js { "userId": "59ed2101-0302-406c-b53f-9705ae1cb357", "accepted": true, "timestamp": "2022-04-16T18:54:36.736+00:00" } ``` ## [Delete Eula Acceptances for deployment](#method.lti/ims/asset_processor_eula.delete_acceptances) [Lti::Ims::AssetProcessorEulaController#delete\_acceptances](https://github.com/instructure/canvas-lms/blob/master/app/controllers/lti/ims/asset_processor_eula_controller.rb) #### `DELETE /api/lti/asset_processor_eulas/:context_external_tool_id/user` **Scope:** `url:DELETE|/api/lti/asset_processor_eulas/:context_external_tool_id/user` Remove the EULA acceptance status for all users within the current deployment. This will allow a tool to reset the EULA acceptance status for all users, and force them to accept the EULA again in the case that the EULA has changed. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Assignment Extensions API for setting extensions on student assignment submissions. These cannot be set for discussion assignments or quizzes. For quizzes, use [Quiz Extensions](/services/canvas/resources/quiz_extensions) instead. #### An AssignmentExtension object looks like: ```js { // The ID of the Assignment the extension belongs to. "assignment_id": 2, // The ID of the Student that needs the assignment extension. "user_id": 3, // Number of times the student is allowed to re-submit the assignment "extra_attempts": 2 } ``` ## [Set extensions for student assignment submissions](#method.assignment_extensions.create) [AssignmentExtensionsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_extensions_controller.rb) #### `POST /api/v1/courses/:course_id/assignments/:assignment_id/extensions` **Scope:** `url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/extensions` \Responses\ * \200 OK\ if the request was successful * \403 Forbidden\ if you are not allowed to extend assignments for this course * \400 Bad Request\ if any of the extensions are invalid #### Request Parameters: | Parameter | Type | Description | | ----------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------ | | `assignment_extensions[][user_id]` | Required `integer` | The ID of the user we want to add assignment extensions for. | | `assignment_extensions[][extra_attempts]` | Required `integer` | Number of times the student is allowed to re-take the assignment over thelimit. | #### Example Request: ```bash { "assignment_extensions": [{ "user_id": 3, "extra_attempts": 2 },{ "user_id": 2, "extra_attempts": 2 }] } ``` #### Example Response: ```js { "assignment_extensions": [AssignmentExtension] } ``` *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Assignment Groups API for accessing Assignment Group and Assignment information. #### A GradingRules object looks like: ```js { // Number of lowest scores to be dropped for each user. "drop_lowest": 1, // Number of highest scores to be dropped for each user. "drop_highest": 1, // Assignment IDs that should never be dropped. "never_drop": [33, 17, 24] } ``` #### An AssignmentGroup object looks like: ```js { // the id of the Assignment Group "id": 1, // the name of the Assignment Group "name": "group2", // the position of the Assignment Group "position": 7, // the weight of the Assignment Group "group_weight": 20, // the sis source id of the Assignment Group "sis_source_id": "1234", // the integration data of the Assignment Group "integration_data": {"5678":"0954"}, // the assignments in this Assignment Group (see the Assignment API for a // detailed list of fields) "assignments": [], // the grading rules that this Assignment Group has "rules": null } ``` ## [List assignment groups](#method.assignment_groups.index) [AssignmentGroupsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_controller.rb) #### `GET /api/v1/courses/:course_id/assignment_groups` **Scope:** `url:GET|/api/v1/courses/:course_id/assignment_groups` Returns the paginated list of assignment groups for the current context. The returned groups are sorted by their position field. #### Request Parameters: | Parameter | Type | Description | | --------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `include[]` | `string` | Associations to include with the group. "discussion\_topic", "all\_dates", "can\_edit","assignment\_visibility" & "submission" are only valid if "assignments" is also included."score\_statistics" requires that the "assignments" and "submission" options are included.The "assignment\_visibility" option additionally requires that the Differentiated Assignments course feature be turned on.If "observed\_users" is passed along with "assignments" and "submission", submissions for observed users will also be included as an array.The "peer\_review" option requires that the Peer Review Grading course feature be turned on and that "assignments" is included. Allowed values: assignments, discussion\_topic, all\_dates, assignment\_visibility, overrides, submission, observed\_users, can\_edit, score\_statistics, peer\_review | | `assignment_ids[]` | `string` | If "assignments" are included, optionally return only assignments having their ID in this array. This argument may also be passed asa comma separated string. | | `exclude_assignment_submission_types[]` | `string` | If "assignments" are included, those with the specified submission typeswill be excluded from the assignment groups. Allowed values: online\_quiz, discussion\_topic, wiki\_page, external\_tool | | `override_assignment_dates` | `boolean` | Apply assignment overrides for each assignment, defaults to true. | | `grading_period_id` | `integer` | The id of the grading period in which assignment groups are being requested(Requires grading periods to exist.) | | `scope_assignments_to_student` | `boolean` | If true, all assignments returned will apply to the current user in thespecified grading period. If assignments apply to other students in thespecified grading period, but not the current user, they will not bereturned. (Requires the grading\_period\_id argument and grading periods toexist. In addition, the current user must be a student.) | Returns a list of [AssignmentGroup](#assignmentgroup) objects. ## [Get an Assignment Group](#method.assignment_groups_api.show) [AssignmentGroupsApiController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_api_controller.rb) #### `GET /api/v1/courses/:course_id/assignment_groups/:assignment_group_id` **Scope:** `url:GET|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id` Returns the assignment group with the given id. #### Request Parameters: | Parameter | Type | Description | | --------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Associations to include with the group. "discussion\_topic" and "assignment\_visibility" and "submission"are only valid if "assignments" is also included. "score\_statistics" is only valid if "submission" and"assignments" are also included. The "assignment\_visibility" option additionally requires that the Differentiated Assignmentscourse feature be turned on. Allowed values: assignments, discussion\_topic, assignment\_visibility, submission, score\_statistics | | `override_assignment_dates` | `boolean` | Apply assignment overrides for each assignment, defaults to true. | | `grading_period_id` | `integer` | The id of the grading period in which assignment groups are being requested(Requires grading periods to exist on the account) | Returns an [AssignmentGroup](#assignmentgroup) object. ## [Create an Assignment Group](#method.assignment_groups_api.create) [AssignmentGroupsApiController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_api_controller.rb) #### `POST /api/v1/courses/:course_id/assignment_groups` **Scope:** `url:POST|/api/v1/courses/:course_id/assignment_groups` Create a new assignment group for this course. #### Request Parameters: | Parameter | Type | Description | | ------------------ | --------- | -------------------------------------------------------------------------------- | | `name` | `string` | The assignment group's name | | `position` | `integer` | The position of this assignment group in relation to the other assignment groups | | `group_weight` | `number` | The percent of the total grade that this assignment group represents | | `sis_source_id` | `string` | The sis source id of the Assignment Group | | `integration_data` | `Object` | The integration data of the Assignment Group | Returns an [AssignmentGroup](#assignmentgroup) object. ## [Edit an Assignment Group](#method.assignment_groups_api.update) [AssignmentGroupsApiController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_api_controller.rb) #### `PUT /api/v1/courses/:course_id/assignment_groups/:assignment_group_id` **Scope:** `url:PUT|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id` Modify an existing Assignment Group. #### Request Parameters: | Parameter | Type | Description | | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | The assignment group's name | | `position` | `integer` | The position of this assignment group in relation to the other assignment groups | | `group_weight` | `number` | The percent of the total grade that this assignment group represents | | `sis_source_id` | `string` | The sis source id of the Assignment Group | | `integration_data` | `Object` | The integration data of the Assignment Group | | `rules` | `string` | The grading rules that are applied within this assignment groupSee the Assignment Group object definition for format | Returns an [AssignmentGroup](#assignmentgroup) object. ## [Destroy an Assignment Group](#method.assignment_groups_api.destroy) [AssignmentGroupsApiController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignment_groups_api_controller.rb) #### `DELETE /api/v1/courses/:course_id/assignment_groups/:assignment_group_id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id` Deletes the assignment group with the given id. #### Request Parameters: | Parameter | Type | Description | | --------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `move_assignments_to` | `integer` | The ID of an active Assignment Group to which the assignments that arecurrently assigned to the destroyed Assignment Group will be assigned.NOTE: If this argument is not provided, any assignments in this AssignmentGroup will be deleted. | Returns an [AssignmentGroup](#assignmentgroup) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). # Assignments API for accessing assignment information. #### An ExternalToolTagAttributes object looks like: ```js { // URL to the external tool "url": "http://instructure.com", // Whether or not there is a new tab for the external tool "new_tab": false, // the identifier for this tool_tag "resource_link_id": "ab81173af98b8c33e66a" } ``` #### A LockInfo object looks like: ```js { // Asset string for the object causing the lock "asset_string": "assignment_4", // (Optional) Time at which this was/will be unlocked. Must be before the due // date. "unlock_at": "2013-01-01T00:00:00-06:00", // (Optional) Time at which this was/will be locked. Must be after the due date. "lock_at": "2013-02-01T00:00:00-06:00", // (Optional) Context module causing the lock. "context_module": "{}", "manually_locked": true } ``` #### A RubricRating object looks like: ```js { "points": 10, "id": "rat1", "description": "Full marks", "long_description": "Student completed the assignment flawlessly." } ``` #### A RubricCriteria object looks like: ```js { "points": 10, // The id of rubric criteria. "id": "crit1", // (Optional) The id of the learning outcome this criteria uses, if any. "learning_outcome_id": "1234", // (Optional) The 3rd party vendor's GUID for the outcome this criteria // references, if any. "vendor_guid": "abdsfjasdfne3jsdfn2", "description": "Criterion 1", "long_description": "Criterion 1 more details", "criterion_use_range": true, "ratings": null, "ignore_for_scoring": true } ``` #### An AssignmentDate object looks like: ```js // Object representing a due date for an assignment or quiz. If the due date // came from an assignment override, it will have an 'id' field. { // (Optional, missing if 'base' is present) id of the assignment override this // date represents "id": 1, // (Optional, present if 'id' is missing) whether this date represents the // assignment's or quiz's default due date "base": true, "title": "Summer Session", // The due date for the assignment. Must be between the unlock date and the lock // date if there are lock dates "due_at": "2013-08-28T23:59:00-06:00", // The unlock date for the assignment. Must be before the due date if there is a // due date. "unlock_at": "2013-08-01T00:00:00-06:00", // The lock date for the assignment. Must be after the due date if there is a // due date. "lock_at": "2013-08-31T23:59:00-06:00" } ``` #### A TurnitinSettings object looks like: ```js { "originality_report_visibility": "after_grading", "s_paper_check": false, "internet_check": false, "journal_check": false, "exclude_biblio": false, "exclude_quoted": false, "exclude_small_matches_type": "percent", "exclude_small_matches_value": 50 } ``` #### A NeedsGradingCount object looks like: ```js // Used by Assignment model { // The section ID "section_id": "123456", // Number of submissions that need grading "needs_grading_count": 5 } ``` #### A ScoreStatistic object looks like: ```js // Used by Assignment model { // Min score "min": 1, // Max score "max": 10, // Mean score "mean": 6, // Upper quartile score "upper_q": 10, // Median score "median": 6, // Lower quartile score "lower_q": 1 } ``` #### An Assignment object looks like: ```js { // the ID of the assignment "id": 4, // the name of the assignment "name": "some assignment", // the assignment description, in an HTML fragment "description": "Do the following:...", // The time at which this assignment was originally created "created_at": "2012-07-01T23:59:00-06:00", // The time at which this assignment was last modified in any way "updated_at": "2012-07-01T23:59:00-06:00", // the due date for the assignment. returns null if not present. NOTE: If this // assignment has assignment overrides, this field will be the due date as it // applies to the user requesting information from the API. "due_at": "2012-07-01T23:59:00-06:00", // the lock date (assignment is locked after this date). returns null if not // present. NOTE: If this assignment has assignment overrides, this field will // be the lock date as it applies to the user requesting information from the // API. "lock_at": "2012-07-01T23:59:00-06:00", // the unlock date (assignment is unlocked after this date) returns null if not // present NOTE: If this assignment has assignment overrides, this field will be // the unlock date as it applies to the user requesting information from the // API. "unlock_at": "2012-07-01T23:59:00-06:00", // whether this assignment has overrides "has_overrides": true, // (Optional) all dates associated with the assignment, if applicable "all_dates": null, // the ID of the course the assignment belongs to "course_id": 123, // the URL to the assignment's web page "html_url": "https://...", // the URL to download all submissions as a zip "submissions_download_url": "https://example.com/courses/:course_id/assignments/:id/submissions?zip=1", // the ID of the assignment's group "assignment_group_id": 2, // Boolean flag indicating whether the assignment requires a due date based on // the account level setting "due_date_required": true, // Allowed file extensions, which take effect if submission_types includes // 'online_upload'. "allowed_extensions": ["docx", "ppt"], // An integer indicating the maximum length an assignment's name may be "max_name_length": 15, // Boolean flag indicating whether or not Turnitin has been enabled for the // assignment. NOTE: This flag will not appear unless your account has the // Turnitin plugin available "turnitin_enabled": true, // Boolean flag indicating whether or not VeriCite has been enabled for the // assignment. NOTE: This flag will not appear unless your account has the // VeriCite plugin available "vericite_enabled": true, // Settings to pass along to turnitin to control what kinds of matches should be // considered. originality_report_visibility can be 'immediate', // 'after_grading', 'after_due_date', or 'never' exclude_small_matches_type can // be null, 'percent', 'words' exclude_small_matches_value: - if type is null, // this will be null also - if type is 'percent', this will be a number between // 0 and 100 representing match size to exclude as a percentage of the document // size. - if type is 'words', this will be number > 0 representing how many // words a match must contain for it to be considered NOTE: This flag will not // appear unless your account has the Turnitin plugin available "turnitin_settings": null, // If this is a group assignment, boolean flag indicating whether or not // students will be graded individually. "grade_group_students_individually": false, // (Optional) assignment's settings for external tools if submission_types // include 'external_tool'. Only url and new_tab are included (new_tab defaults // to false). Use the 'External Tools' API if you need more information about // an external tool. "external_tool_tag_attributes": null, // Boolean indicating if peer reviews are required for this assignment "peer_reviews": false, // Boolean indicating peer reviews are assigned automatically. If false, the // teacher is expected to manually assign peer reviews. "automatic_peer_reviews": false, // Integer representing the amount of reviews each user is assigned. NOTE: This // key is NOT present unless you have automatic_peer_reviews set to true. "peer_review_count": 0, // String representing a date the reviews are due by. Must be a date that occurs // after the default due date. If blank, or date is not after the assignment's // due date, the assignment's due date will be used. NOTE: This key is NOT // present unless you have automatic_peer_reviews set to true. "peer_reviews_assign_at": "2012-07-01T23:59:00-06:00", // Boolean representing whether or not members from within the same group on a // group assignment can be assigned to peer review their own group's work "intra_group_peer_reviews": false, // The ID of the assignment’s group set, if this is a group assignment. For // group discussions, set group_category_id on the discussion topic, not the // linked assignment. "group_category_id": 1, // if the requesting user has grading rights, the number of submissions that // need grading. "needs_grading_count": 17, // if the requesting user has grading rights and the // 'needs_grading_count_by_section' flag is specified, the number of submissions // that need grading split out by section. NOTE: This key is NOT present unless // you pass the 'needs_grading_count_by_section' argument as true. ANOTHER // NOTE: it's possible to be enrolled in multiple sections, and if a student is // setup that way they will show an assignment that needs grading in multiple // sections (effectively the count will be duplicated between sections) "needs_grading_count_by_section": [{"section_id":"123456","needs_grading_count":5}, {"section_id":"654321","needs_grading_count":0}], // the sorting order of the assignment in the group "position": 1, // (optional, present if Sync Grades to SIS feature is enabled) "post_to_sis": true, // (optional, Third Party unique identifier for Assignment) "integration_id": "12341234", // (optional, Third Party integration data for assignment) "integration_data": {"5678":"0954"}, // the maximum points possible for the assignment "points_possible": 12.0, // the types of submissions allowed for this assignment list containing one or // more of the following: 'discussion_topic', 'online_quiz', 'on_paper', 'none', // 'external_tool', 'online_text_entry', 'online_url', 'online_upload', // 'media_recording', 'student_annotation' "submission_types": ["online_text_entry"], // If true, the assignment has been submitted to by at least one student "has_submitted_submissions": true, // The type of grading the assignment receives; one of 'pass_fail', 'percent', // 'letter_grade', 'gpa_scale', 'points' "grading_type": "points", // The id of the grading standard being applied to this assignment. Valid if // grading_type is 'letter_grade' or 'gpa_scale'. "grading_standard_id": null, // Whether the assignment is published "published": true, // Whether the assignment's 'published' state can be changed to false. Will be // false if there are student submissions for the assignment. "unpublishable": false, // Whether the assignment is only visible to overrides. "only_visible_to_overrides": false, // Whether or not this is locked for the user. "locked_for_user": false, // (Optional) Information for the user about the lock. Present when // locked_for_user is true. "lock_info": null, // (Optional) An explanation of why this is locked for the user. Present when // locked_for_user is true. "lock_explanation": "This assignment is locked until September 1 at 12:00am", // (Optional) id of the associated quiz (applies only when submission_types is // ['online_quiz']) "quiz_id": 620, // (Optional) whether anonymous submissions are accepted (applies only to quiz // assignments) "anonymous_submissions": false, // (Optional) the DiscussionTopic associated with the assignment, if applicable "discussion_topic": null, // (Optional) Boolean indicating if assignment will be frozen when it is copied. // NOTE: This field will only be present if the AssignmentFreezer plugin is // available for your account. "freeze_on_copy": false, // (Optional) Boolean indicating if assignment is frozen for the calling user. // NOTE: This field will only be present if the AssignmentFreezer plugin is // available for your account. "frozen": false, // (Optional) Array of frozen attributes for the assignment. Only account // administrators currently have permission to change an attribute in this list. // Will be empty if no attributes are frozen for this assignment. Possible // frozen attributes are: title, description, lock_at, points_possible, // grading_type, submission_types, assignment_group_id, allowed_extensions, // group_category_id, notify_of_update, peer_reviews NOTE: This field will only // be present if the AssignmentFreezer plugin is available for your account. "frozen_attributes": ["title"], // (Optional) If 'submission' is included in the 'include' parameter, includes a // Submission object that represents the current user's (user who is requesting // information from the api) current submission for the assignment. See the // Submissions API for an example response. If the user does not have a // submission, this key will be absent. "submission": null, // (Optional) If true, the rubric is directly tied to grading the assignment. // Otherwise, it is only advisory. Included if there is an associated rubric. "use_rubric_for_grading": true, // (Optional) An object describing the basic attributes of the rubric, including // the point total. Included if there is an associated rubric. "rubric_settings": {"points_possible":"12"}, // (Optional) A list of scoring criteria and ratings for each rubric criterion. // Included if there is an associated rubric. "rubric": null, // (Optional) If 'assignment_visibility' is included in the 'include' parameter, // includes an array of student IDs who can see this assignment. "assignment_visibility": [137, 381, 572], // (Optional) If 'overrides' is included in the 'include' parameter, includes an // array of assignment override objects. "overrides": null, // (Optional) If true, the assignment will be omitted from the student's final // grade "omit_from_final_grade": true, // (Optional) If true, the assignment will not be shown in any gradebooks "hide_in_gradebook": true, // Boolean indicating if the assignment is moderated. "moderated_grading": true, // The maximum number of provisional graders who may issue grades for this // assignment. Only relevant for moderated assignments. Must be a positive // value, and must be set to 1 if the course has fewer than two active // instructors. Otherwise, the maximum value is the number of active instructors // in the course minus one, or 10 if the course has more than 11 active // instructors. "grader_count": 3, // The user ID of the grader responsible for choosing final grades for this // assignment. Only relevant for moderated assignments. "final_grader_id": 3, // Boolean indicating if provisional graders' comments are visible to other // provisional graders. Only relevant for moderated assignments. "grader_comments_visible_to_graders": true, // Boolean indicating if provisional graders' identities are hidden from other // provisional graders. Only relevant for moderated assignments with // grader_comments_visible_to_graders set to true. "graders_anonymous_to_graders": true, // Boolean indicating if provisional grader identities are visible to the final // grader. Only relevant for moderated assignments. "grader_names_visible_to_final_grader": true, // Boolean indicating if the assignment is graded anonymously. If true, graders // cannot see student identities. "anonymous_grading": true, // The number of submission attempts a student can make for this assignment. -1 // is considered unlimited. "allowed_attempts": 2, // Whether the assignment has manual posting enabled. Only relevant for courses // using New Gradebook. "post_manually": true, // (Optional) If 'score_statistics' and 'submission' are included in the // 'include' parameter and statistics are available, includes the min, max, and // mode for this assignment "score_statistics": null, // (Optional) If retrieving a single assignment and 'can_submit' is included in // the 'include' parameter, flags whether user has the right to submit the // assignment (i.e. checks enrollment dates, submission types, locked status, // attempts remaining, etc...). Including 'can submit' automatically includes // 'submission' in the include parameter. Not available when observed_users are // included. "can_submit": true, // (Optional) The academic benchmark(s) associated with the assignment or the // assignment's rubric. Only included if 'ab_guid' is included in the 'include' // parameter. "ab_guid": ["ABCD", "EFGH"], // (Optional) The account-level academic integrity pledge text a student must // accept before submitting this assignment. Only present if // 'academic_integrity_pledge' is included in the 'include' parameter AND the // pledge is enabled for the account; otherwise the key is omitted. When present // but the pledge does not apply to this particular assignment (e.g. external // tool assignments or Canvas Career courses), the value is null. "academic_integrity_pledge": "This submission reflects my own ideas and work", // The id of the attachment to be annotated by students. Relevant only if // submission_types includes 'student_annotation'. "annotatable_attachment_id": null, // (Optional) Boolean indicating whether student names are anonymized "anonymize_students": false, // (Optional) Boolean indicating whether the Respondus LockDown Browser® is // required for this assignment. "require_lockdown_browser": false, // (Optional) Boolean indicating whether this assignment has important dates. "important_dates": false, // (Optional, Deprecated) Boolean indicating whether notifications are muted for // this assignment. "muted": false, // Boolean indicating whether peer reviews are anonymous. "anonymous_peer_reviews": false, // Boolean indicating whether instructor anotations are anonymous. "anonymous_instructor_annotations": false, // Boolean indicating whether this assignment has graded submissions. "graded_submissions_exist": false, // Boolean indicating whether this is a quiz lti assignment. "is_quiz_assignment": false, // Boolean indicating whether this assignment is in a closed grading period. "in_closed_grading_period": false, // Boolean indicating whether this assignment can be duplicated. "can_duplicate": false, // If this assignment is a duplicate, it is the original assignment's course_id "original_course_id": 4, // If this assignment is a duplicate, it is the original assignment's id "original_assignment_id": 4, // If this assignment is a duplicate, it is the original assignment's // lti_resource_link_id "original_lti_resource_link_id": 4, // If this assignment is a duplicate, it is the original assignment's name "original_assignment_name": "some assignment", // If this assignment is a duplicate, it is the original assignment's quiz_id "original_quiz_id": 4, // String indicating what state this assignment is in. "workflow_state": "unpublished" } ``` #### A BasicUser object looks like: ```js { // The user's ID "id": "123456", // The user's name "name": "Dankey Kang" } ``` #### An AssignmentOverride object looks like: ```js { // the ID of the assignment override "id": 4, // the ID of the assignment the override applies to (present if the override // applies to an assignment) "assignment_id": 123, // the ID of the quiz the override applies to (present if the override applies // to a quiz) "quiz_id": 123, // the ID of the module the override applies to (present if the override applies // to a module) "context_module_id": 123, // the ID of the discussion the override applies to (present if the override // applies to an ungraded discussion) "discussion_topic_id": 123, // the ID of the page the override applies to (present if the override applies // to a page) "wiki_page_id": 123, // the ID of the file the override applies to (present if the override applies // to a file) "attachment_id": 123, // the IDs of the override's target students (present if the override targets an // ad-hoc set of students) "student_ids": [1, 2, 3], // the ID of the override's target group (present if the override targets a // group and the assignment is a group assignment) "group_id": 2, // the ID of the overrides's target section (present if the override targets a // section) "course_section_id": 1, // the title of the override "title": "an assignment override", // the overridden due at (present if due_at is overridden) "due_at": "2012-07-01T23:59:00-06:00", // the overridden all day flag (present if due_at is overridden) "all_day": true, // the overridden all day date (present if due_at is overridden) "all_day_date": "2012-07-01", // the overridden unlock at (present if unlock_at is overridden) "unlock_at": "2012-07-01T23:59:00-06:00", // the overridden lock at, if any (present if lock_at is overridden) "lock_at": "2012-07-01T23:59:00-06:00" } ``` ## [Delete an assignment](#method.assignments.destroy) [AssignmentsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_controller.rb) #### `DELETE /api/v1/courses/:course_id/assignments/:id` **Scope:** `url:DELETE|/api/v1/courses/:course_id/assignments/:id` Delete the given assignment. #### Example Request: ```bash curl https:///api/v1/courses//assignments/ \ -X DELETE \ -H 'Authorization: Bearer ' ``` Returns an [Assignment](#assignment) object. ## [List assignments](#method.assignments_api.index) [AssignmentsApiController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `GET /api/v1/courses/:course_id/assignments` **Scope:** `url:GET|/api/v1/courses/:course_id/assignments` #### `GET /api/v1/courses/:course_id/assignment_groups/:assignment_group_id/assignments` **Scope:** `url:GET|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id/assignments` Returns the paginated list of assignments for the current course or assignment group. #### Request Parameters: | Parameter | Type | Description | | -------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Optional information to include with each assignment:submission:: The current user's current +Submission+assignment\_visibility:: An array of ids of students who can see the assignmentall\_dates:: An array of +AssignmentDate+ structures, one for each override, and also a +base+ if the assignment has an "Everyone" / "Everyone Else" dateoverrides:: An array of +AssignmentOverride+ structuresobserved\_users:: An array of submissions for observed userscan\_edit:: an extra Boolean value will be included with each +Assignment+ (and +AssignmentDate+ if +all\_dates+ is supplied) to indicate whether the caller can edit the assignment or date. Moderated grading and closed grading periods may restrict a user's ability to edit an assignment.score\_statistics:: An object containing min, max, and mean score on this assignment. This will not be included for students if there are less than 5 graded assignments or if disabled by the instructor. Only valid if 'submission' is also included.ab\_guid:: An array of guid strings for academic benchmarks Allowed values: submission, assignment\_visibility, all\_dates, overrides, observed\_users, can\_edit, score\_statistics, ab\_guid | | `search_term` | `string` | The partial title of the assignments to match and return. | | `override_assignment_dates` | `boolean` | Apply assignment overrides for each assignment, defaults to true. | | `needs_grading_count_by_section` | `boolean` | Split up "needs\_grading\_count" by sections into the "needs\_grading\_count\_by\_section" key, defaults to false | | `bucket` | `string` | If included, only return certain assignments depending on due date and submission status. Allowed values: `past`, `overdue`, `undated`, `ungraded`, `unsubmitted`, `upcoming`, `future` | | `assignment_ids[]` | `string` | if set, return only assignments specified | | `order_by` | `string` | Determines the order of the assignments. Defaults to "position". Allowed values: `position`, `name`, `due_at` | | `post_to_sis` | `boolean` | Return only assignments that have post\_to\_sis set or not set. | | `new_quizzes` | `boolean` | Return only New Quizzes assignments | Returns a list of [Assignment](#assignment) objects. ## [List assignments for user](#method.assignments_api.user_index) [AssignmentsApiController#user\_index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `GET /api/v1/users/:user_id/courses/:course_id/assignments` **Scope:** `url:GET|/api/v1/users/:user_id/courses/:course_id/assignments` Returns the paginated list of assignments for the specified user if the current user has rights to view. See [List assignments](#method.assignments_api.index) for valid arguments. ## [Duplicate assignment](#method.assignments_api.duplicate) [AssignmentsApiController#duplicate](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `POST /api/v1/courses/:course_id/assignments/:assignment_id/duplicate` **Scope:** `url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/duplicate` Duplicate an assignment and return a json based on result\_type argument. #### Request Parameters: | Parameter | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `result_type` | `string` | Optional information:When the root account has the feature newquizzes\_on\_quiz\_page enabledand this argument is set to "Quiz" the response will be serialized into aquiz format;When this argument isn't specified the response will be serialized into anassignment format; Allowed values: Quiz | #### Example Request: ```bash curl -X POST -H 'Authorization: Bearer ' \ https:///api/v1/courses/123/assignments/123/duplicate ``` ```bash curl -X POST -H 'Authorization: Bearer ' \ https:///api/v1/courses/123/assignments/123/duplicate?result_type=Quiz ``` Returns an [Assignment](#assignment) object. ## [List group members for a student on an assignment](#method.assignments_api.student_group_members) [AssignmentsApiController#student\_group\_members](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `GET /api/v1/courses/:course_id/assignments/:assignment_id/users/:user_id/group_members` **Scope:** `url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/users/:user_id/group_members` Returns student ids and names for the group. #### Example Request: ```bash curl https:///api/v1/courses/1/assignments/1/users/1/group_members ``` Returns a list of [BasicUser](#basicuser) objects. ## [Get a single assignment](#method.assignments_api.show) [AssignmentsApiController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `GET /api/v1/courses/:course_id/assignments/:id` **Scope:** `url:GET|/api/v1/courses/:course_id/assignments/:id` Returns the assignment with the given id. #### Request Parameters: | Parameter | Type | Description | | -------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` | Associations to include with the assignment. The "assignment\_visibility" optionrequires that the Differentiated Assignments course feature be turned on. If"observed\_users" is passed, submissions for observed users will also be included.For "score\_statistics" to be included, the "submission" option must also be set.The "peer\_review" option returns peer review sub assignment data if it exists, regardlessof the Peer Review Allocation and Grading feature state. If no peer review sub assignmentexists, the feature must be enabled to receive a null value; otherwise the key is omitted.The "academic\_integrity\_pledge" option returns the account-level academic integritypledge text a student must accept before submitting this assignment. The key is onlypresent when the pledge is enabled for the account; when present but the pledge does notapply to this assignment (e.g. external tool assignments or Canvas Career courses) thevalue is null. Allowed values: submission, assignment\_visibility, overrides, observed\_users, can\_edit, score\_statistics, ab\_guid, peer\_review, academic\_integrity\_pledge | | `override_assignment_dates` | `boolean` | Apply assignment overrides to the assignment, defaults to true. | | `needs_grading_count_by_section` | `boolean` | Split up "needs\_grading\_count" by sections into the "needs\_grading\_count\_by\_section" key, defaults to false | | `all_dates` | `boolean` | All dates associated with the assignment, if applicable | Returns an [Assignment](#assignment) object. ## [Create an assignment](#method.assignments_api.create) [AssignmentsApiController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `POST /api/v1/courses/:course_id/assignments` **Scope:** `url:POST|/api/v1/courses/:course_id/assignments` Create a new assignment for this course. The assignment is created in the active state. #### Request Parameters: | Parameter | Type | Description | | --------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `assignment[name]` | Required `string` | The assignment name. | | `assignment[position]` | `integer` | The position of this assignment in the group when displayingassignment lists. | | `assignment[submission_types][]` | `string` | List of supported submission types for the assignment.Unless the assignment is allowing online submissions, the array shouldonly have one element.If not allowing online submissions, your options are:"online\_quiz""none""on\_paper""discussion\_topic""external\_tool"If you are allowing online submissions, you can have one or manyallowed submission types:"online\_upload""online\_text\_entry""online\_url""media\_recording" (Only valid when the Kaltura plugin is enabled)"student\_annotation" Allowed values: online\_quiz, none, on\_paper, discussion\_topic, external\_tool, online\_upload, online\_text\_entry, online\_url, media\_recording, student\_annotation | | `assignment[allowed_extensions][]` | `string` | Allowed extensions if submission\_types includes "online\_upload"Example:allowed\_extensions: \["docx","ppt"] | | `assignment[turnitin_enabled]` | `boolean` | Only applies when the Turnitin plugin is enabled for a course andthe submission\_types array includes "online\_upload".Toggles Turnitin submissions for the assignment.Will be ignored if Turnitin is not available for the course. | | `assignment[vericite_enabled]` | `boolean` | Only applies when the VeriCite plugin is enabled for a course andthe submission\_types array includes "online\_upload".Toggles VeriCite submissions for the assignment.Will be ignored if VeriCite is not available for the course. | | `assignment[turnitin_settings]` | `string` | Settings to send along to turnitin. See Assignment object definition forformat. | | `assignment[integration_data]` | `string` | Data used for SIS integrations. Requires admin-level token with the "Manage SIS" permission. JSON string required. | | `assignment[integration_id]` | `string` | Unique ID from third party integrations | | `assignment[peer_reviews]` | `boolean` | If submission\_types does not include external\_tool,discussion\_topic,online\_quiz, or on\_paper, determines whether or not peer reviewswill be turned on for the assignment. | | `assignment[automatic_peer_reviews]` | `boolean` | Whether peer reviews will be assigned automatically by Canvas or ifteachers must manually assign peer reviews. Does not apply if peer reviewsare not enabled. | | `assignment[notify_of_update]` | `boolean` | If true, Canvas will send a notification to students in the classnotifying them that the content has changed. | | `assignment[group_category_id]` | `integer` | If present, the assignment will become a group assignment assignedto the group. | | `assignment[grade_group_students_individually]` | `integer` | If this is a group assignment, teachers have the options to gradestudents individually. If false, Canvas will apply the assignment'sscore to each member of the group. If true, the teacher can manuallyassign scores to each member of the group. | | `assignment[external_tool_tag_attributes]` | `string` | Hash of external tool parameters if submission\_types is \["external\_tool"].See Assignment object definition for format. | | `assignment[points_possible]` | `number` | The maximum points possible on the assignment. | | `assignment[grading_type]` | `string` | The strategy used for grading the assignment.The assignment defaults to "points" if this field is omitted. Allowed values: pass\_fail, percent, letter\_grade, gpa\_scale, points, not\_graded | | `assignment[due_at]` | `DateTime` | The day/time the assignment is due. Must be between the lock dates if there are lock dates.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[lock_at]` | `DateTime` | The day/time the assignment is locked after. Must be after the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[unlock_at]` | `DateTime` | The day/time the assignment is unlocked. Must be before the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[description]` | `string` | The assignment's description, supports HTML. | | `assignment[assignment_group_id]` | `integer` | The assignment group id to put the assignment in.Defaults to the top assignment group in the course. | | `assignment[assignment_overrides][]` | `AssignmentOverride` | List of overrides for the assignment. | | `assignment[only_visible_to_overrides]` | `boolean` | Whether this assignment is only visible to overrides(Only useful if 'differentiated assignments' account setting is on) | | `assignment[published]` | `boolean` | Whether this assignment is published.(Only useful if 'draft state' account setting is on)Unpublished assignments are not visible to students. | | `assignment[grading_standard_id]` | `integer` | The grading standard id to set for the course. If no value is provided for this argument the current grading\_standard will be un-set from this course.This will update the grading\_type for the course to 'letter\_grade' unless it is already 'gpa\_scale'. | | `assignment[omit_from_final_grade]` | `boolean` | Whether this assignment is counted towards a student's final grade. | | `assignment[hide_in_gradebook]` | `boolean` | Whether this assignment is shown in the gradebook. | | `assignment[quiz_lti]` | `boolean` | Whether this assignment should use the Quizzes 2 LTI tool. Sets thesubmission type to 'external\_tool' and configures the external toolattributes to use the Quizzes 2 LTI tool configured for this course.Has no effect if no Quizzes 2 LTI tool is configured. | | `assignment[moderated_grading]` | `boolean` | Whether this assignment is moderated. | | `assignment[grader_count]` | `integer` | The maximum number of provisional graders who may issue grades for thisassignment. Only relevant for moderated assignments. Must be a positivevalue, and must be set to 1 if the course has fewer than two activeinstructors. Otherwise, the maximum value is the number of activeinstructors in the course minus one, or 10 if the course has more than 11active instructors. | | `assignment[final_grader_id]` | `integer` | The user ID of the grader responsible for choosing final grades for thisassignment. Only relevant for moderated assignments. | | `assignment[grader_comments_visible_to_graders]` | `boolean` | Boolean indicating if provisional graders' comments are visible to otherprovisional graders. Only relevant for moderated assignments. | | `assignment[graders_anonymous_to_graders]` | `boolean` | Boolean indicating if provisional graders' identities are hidden fromother provisional graders. Only relevant for moderated assignments. | | `assignment[graders_names_visible_to_final_grader]` | `boolean` | Boolean indicating if provisional grader identities are visible to thethe final grader. Only relevant for moderated assignments. | | `assignment[anonymous_grading]` | `boolean` | Boolean indicating if the assignment is graded anonymously. If true,graders cannot see student identities. | | `assignment[allowed_attempts]` | `integer` | The number of submission attempts allowed for this assignment. Set to -1 for unlimited attempts. | | `assignment[annotatable_attachment_id]` | `integer` | The Attachment ID of the document being annotated.Only applies when submission\_types includes "student\_annotation". | | `assignment[asset_processors][]` | `Array` | Document processors for this assignment. New document processors can only be addedvia the interactive LTI Deep Linking flow (in a browser), not via API token or JWT authentication.Deletion of document processors (passing an empty array) is allowed via API. | | `assignment[peer_review][points_possible]` | `number` | The maximum points possible for peer reviews. | | `assignment[peer_review][grading_type]` | `string` | The strategy used for grading peer reviews.Defaults to "points" if this field is omitted. Allowed values: pass\_fail, percent, letter\_grade, gpa\_scale, points | | `assignment[peer_review][due_at]` | `DateTime` | The day/time the peer reviews are due. Must be between the lock dates if there are lock dates.Accepts times in ISO 8601 format, e.g. 2025-08-20T12:10:00Z. | | `assignment[peer_review][lock_at]` | `DateTime` | The day/time the peer reviews are locked after. Must be after the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2025-08-25T12:10:00Z. | | `assignment[peer_review][unlock_at]` | `DateTime` | The day/time the peer reviews are unlocked. Must be before the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2025-08-15T12:10:00Z. | | `assignment[peer_review][peer_review_overrides][]` | `AssignmentOverride` | List of overrides for the peer reviews. | Returns an [Assignment](#assignment) object. ## [Edit an assignment](#method.assignments_api.update) [AssignmentsApiController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `PUT /api/v1/courses/:course_id/assignments/:id` **Scope:** `url:PUT|/api/v1/courses/:course_id/assignments/:id` Modify an existing assignment. #### Request Parameters: | Parameter | Type | Description | | --------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `assignment[name]` | `string` | The assignment name. | | `assignment[position]` | `integer` | The position of this assignment in the group when displayingassignment lists. | | `assignment[submission_types][]` | `string` | Only applies if the assignment doesn't have student submissions.List of supported submission types for the assignment.Unless the assignment is allowing online submissions, the array shouldonly have one element.If not allowing online submissions, your options are:"online\_quiz""none""on\_paper""discussion\_topic""external\_tool"If you are allowing online submissions, you can have one or manyallowed submission types:"online\_upload""online\_text\_entry""online\_url""media\_recording" (Only valid when the Kaltura plugin is enabled)"student\_annotation" Allowed values: online\_quiz, none, on\_paper, discussion\_topic, external\_tool, online\_upload, online\_text\_entry, online\_url, media\_recording, student\_annotation | | `assignment[allowed_extensions][]` | `string` | Allowed extensions if submission\_types includes "online\_upload"Example:allowed\_extensions: \["docx","ppt"] | | `assignment[turnitin_enabled]` | `boolean` | Only applies when the Turnitin plugin is enabled for a course andthe submission\_types array includes "online\_upload".Toggles Turnitin submissions for the assignment.Will be ignored if Turnitin is not available for the course. | | `assignment[vericite_enabled]` | `boolean` | Only applies when the VeriCite plugin is enabled for a course andthe submission\_types array includes "online\_upload".Toggles VeriCite submissions for the assignment.Will be ignored if VeriCite is not available for the course. | | `assignment[turnitin_settings]` | `string` | Settings to send along to turnitin. See Assignment object definition forformat. | | `assignment[sis_assignment_id]` | `string` | The sis id of the Assignment | | `assignment[integration_data]` | `string` | Data used for SIS integrations. Requires admin-level token with the "Manage SIS" permission. JSON string required. | | `assignment[integration_id]` | `string` | Unique ID from third party integrations | | `assignment[peer_reviews]` | `boolean` | If submission\_types does not include external\_tool,discussion\_topic,online\_quiz, or on\_paper, determines whether or not peer reviewswill be turned on for the assignment. | | `assignment[automatic_peer_reviews]` | `boolean` | Whether peer reviews will be assigned automatically by Canvas or ifteachers must manually assign peer reviews. Does not apply if peer reviewsare not enabled. | | `assignment[notify_of_update]` | `boolean` | If true, Canvas will send a notification to students in the classnotifying them that the content has changed. | | `assignment[group_category_id]` | `integer` | If present, the assignment will become a group assignment assignedto the group. | | `assignment[grade_group_students_individually]` | `integer` | If this is a group assignment, teachers have the options to gradestudents individually. If false, Canvas will apply the assignment'sscore to each member of the group. If true, the teacher can manuallyassign scores to each member of the group. | | `assignment[external_tool_tag_attributes]` | `string` | Hash of external tool parameters if submission\_types is \["external\_tool"].See Assignment object definition for format. | | `assignment[points_possible]` | `number` | The maximum points possible on the assignment. | | `assignment[grading_type]` | `string` | The strategy used for grading the assignment.The assignment defaults to "points" if this field is omitted. Allowed values: pass\_fail, percent, letter\_grade, gpa\_scale, points, not\_graded | | `assignment[due_at]` | `DateTime` | The day/time the assignment is due.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[lock_at]` | `DateTime` | The day/time the assignment is locked after. Must be after the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[unlock_at]` | `DateTime` | The day/time the assignment is unlocked. Must be before the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. | | `assignment[description]` | `string` | The assignment's description, supports HTML. | | `assignment[assignment_group_id]` | `integer` | The assignment group id to put the assignment in.Defaults to the top assignment group in the course. | | `assignment[assignment_overrides][]` | `AssignmentOverride` | List of overrides for the assignment.If the +assignment\[assignment\_overrides]+ key is absent, any existingoverrides are kept as is. If the +assignment\[assignment\_overrides]+ key ispresent, existing overrides are updated or deleted (and new ones created,as necessary) to match the provided list. | | `assignment[only_visible_to_overrides]` | `boolean` | Whether this assignment is only visible to overrides(Only useful if 'differentiated assignments' account setting is on) | | `assignment[published]` | `boolean` | Whether this assignment is published.(Only useful if 'draft state' account setting is on)Unpublished assignments are not visible to students. | | `assignment[grading_standard_id]` | `integer` | The grading standard id to set for the course. If no value is provided for this argument the current grading\_standard will be un-set from this course.This will update the grading\_type for the course to 'letter\_grade' unless it is already 'gpa\_scale'. | | `assignment[omit_from_final_grade]` | `boolean` | Whether this assignment is counted towards a student's final grade. | | `assignment[hide_in_gradebook]` | `boolean` | Whether this assignment is shown in the gradebook. | | `assignment[moderated_grading]` | `boolean` | Whether this assignment is moderated. | | `assignment[grader_count]` | `integer` | The maximum number of provisional graders who may issue grades for thisassignment. Only relevant for moderated assignments. Must be a positivevalue, and must be set to 1 if the course has fewer than two activeinstructors. Otherwise, the maximum value is the number of activeinstructors in the course minus one, or 10 if the course has more than 11active instructors. | | `assignment[final_grader_id]` | `integer` | The user ID of the grader responsible for choosing final grades for thisassignment. Only relevant for moderated assignments. | | `assignment[grader_comments_visible_to_graders]` | `boolean` | Boolean indicating if provisional graders' comments are visible to otherprovisional graders. Only relevant for moderated assignments. | | `assignment[graders_anonymous_to_graders]` | `boolean` | Boolean indicating if provisional graders' identities are hidden fromother provisional graders. Only relevant for moderated assignments. | | `assignment[graders_names_visible_to_final_grader]` | `boolean` | Boolean indicating if provisional grader identities are visible to thethe final grader. Only relevant for moderated assignments. | | `assignment[anonymous_grading]` | `boolean` | Boolean indicating if the assignment is graded anonymously. If true,graders cannot see student identities. | | `assignment[allowed_attempts]` | `integer` | The number of submission attempts allowed for this assignment. Set to -1 or null forunlimited attempts. | | `assignment[annotatable_attachment_id]` | `integer` | The Attachment ID of the document being annotated.Only applies when submission\_types includes "student\_annotation". | | `assignment[asset_processors][]` | `Array` | Document processors for this assignment. New document processors can only be addedvia the interactive LTI Deep Linking flow (in a browser), not via API token or JWT authentication.Deletion of document processors (passing an empty array) is allowed via API. | | `assignment[force_updated_at]` | `boolean` | If true, updated\_at will be set even if no changes were made. | | `assignment[peer_review][points_possible]` | `number` | The maximum points possible for peer reviews. | | `assignment[peer_review][grading_type]` | `string` | The strategy used for grading peer reviews.Defaults to "points" if this field is omitted. Allowed values: pass\_fail, percent, letter\_grade, gpa\_scale, points | | `assignment[peer_review][due_at]` | `DateTime` | The day/time the peer reviews are due. Must be between the lock dates if there are lock dates.Accepts times in ISO 8601 format, e.g. 2025-08-20T12:10:00Z. | | `assignment[peer_review][lock_at]` | `DateTime` | The day/time the peer reviews are locked after. Must be after the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2025-08-25T12:10:00Z. | | `assignment[peer_review][unlock_at]` | `DateTime` | The day/time the peer reviews are unlocked. Must be before the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2025-08-15T12:10:00Z. | | `assignment[peer_review][peer_review_overrides][]` | `AssignmentOverride` | List of overrides for the peer reviews.When updating overrides:- Include "id" to update an existing override- Omit "id" to create a new override- Omit an override from the list to delete it | | `assignment[submission_types][]` | `string` | **\[DEPRECATED]** Effective 2021-05-26 (notice given 2021-02-18) Only applies if the assignment doesn't have student submissions. | Returns an [Assignment](#assignment) object. ## [Bulk update assignment dates](#method.assignments_api.bulk_update) [AssignmentsApiController#bulk\_update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/assignments_api_controller.rb) #### `PUT /api/v1/courses/:course_id/assignments/bulk_update` **Scope:** `url:PUT|/api/v1/courses/:course_id/assignments/bulk_update` Update due dates and availability dates for multiple assignments in a course. Accepts a JSON array of objects containing two keys each: +id+, the assignment id, and +all\_dates+, an array of +AssignmentDate+ structures containing the base and/or override dates for the assignment, as returned from the [List assignments](#method.assignments_api.index) endpoint with +include\[]=all\_dates+. This endpoint cannot create or destroy assignment overrides; any existing assignment overrides that are not referenced in the arguments will be left alone. If an override is given, any dates that are not supplied with it will be defaulted. To clear a date, specify null explicitly. All referenced assignments will be validated before any are saved. A list of errors will be returned if any provided dates are invalid, and no changes will be saved. The bulk update is performed in a background job, use the [Progress API](https://developerdocs.instructure.com/services/canvas/resources/pages/3xnEhMZQuJstdXB8KHiv#method.progress.show) to check its status. #### Example Request: ```bash curl 'https:///api/v1/courses/1/assignments/bulk_update' \ -X PUT \ --data '[{ "id": 1, "all_dates": [{ "base": true, "due_at": "2020-08-29T23:59:00-06:00" }, { "id": 2, "due_at": "2020-08-30T23:59:00-06:00" }] }]' \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " ``` Returns a [Progress](/services/canvas/resources/progress#progress) object. ## [List assignment overrides](#method.assignment_overrides.index)
Set this to '1' if you want to end all of the user's Canvas web sessions. Without this argument, the endpoint will leave web sessions intact.
Additionally, if the user logged in to Canvas via a delegated authentication provider, and the provider supports Single Log Out functionality, the response will contain a forward\_url key. If you are still in control of the user's browsing session, it is recommended to then redirect them to this URL, in order to also log them out from where their session originated. Beware that it is unlikely that control will be returned to your application after this redirect.
The scopes to associate with the token.Ignored if the default developer key does not have the "enable scopes" option enabled.In such cases, the token will inherit the user's permissions instead.
The ID of the user, or "self" for the current user.The requesting user may only trigger a scan for themselves.
The ID of the user, or "self" for the current user.The requesting user may only retrieve their own statistics.
When present, only include courses that belong to the given enrollmentterm(s). Accepts a single term id or an array(enrollment\_term\_id\[]=1\&enrollment\_term\_id\[]=2), and each value may be aterm id or SIS term id. Returns 404 if any given term does not exist inthis account.
The ID of the user, or "self" for the current user.The requesting user may only retrieve their own terms.
When included, searches available account calendars for the term. Returns matchingresults. Term must be at least 2 characters.
Allow administrators with manage\_account\_calendar\_events permissionto create events on this calendar, and allow users to view thiscalendar and its events.
manage\_account\_calendar\_events
When true, users will automatically see events from this account in theircalendar, even if they haven't manually added that calendar.
When included, searches all descendent accounts of provided account for theterm. Returns matching results. Term must be at least 2 characters. Can becombined with a filter value.
When included, only returns calendars that are either visible or hidden. Canbe combined with a search term. Allowed values: visible, hidden
visible
hidden
The start date and time of the notification in ISO8601 format.e.g. 2014-01-01T01:00Z
The end date and time of the notification in ISO8601 format.e.g. 2014-01-01T01:00Z
The icon to display with the notification.Note: Defaults to warning. Allowed values: warning, information, question, error, calendar
warning
information
question
error
calendar
The role(s) to send global notification to. Note: ommitting this field will send to everyoneExample:account\_notification\_roles: \["StudentEnrollment", "TeacherEnrollment"]
Array of additional information to include."description\_html":: an HTML description of the report, with example output"parameters\_html":: an HTML form for the report parameters Allowed values: description\_html, params\_html
description\_html
params\_html
The parameters will vary for each report. To fetch a listof available parameters for each report, see List Available Reports.A few example parameters have been provided below. Note that the exampleparameters provided below may not be valid for every report.
If true, no message will be sentto the user upon completion of the report.
The id of the course to report on.Note: this parameter has been listed to serve as an example and may not bevalid for every report.
If true, user data will be included. Iffalse, user data will be omitted. Note: this parameter has been listed toserve as an example and may not be valid for every report.
Array of additional information to include."lti\_guid":: the 'tool\_consumer\_instance\_guid' that will be sent for this account on LTI launches"registration\_settings":: returns info about the privacy policy and terms of use"services":: returns services and whether they are enabled (requires account management permissions)"course\_count":: returns the number of courses directly under each account"sub\_account\_count":: returns the number of sub-accounts directly under each account Allowed values: lti\_guid, registration\_settings, services, course\_count, sub\_account\_count
lti\_guid
registration\_settings
services
course\_count
sub\_account\_count
Array of additional information to include."lti\_guid":: the 'tool\_consumer\_instance\_guid' that will be sent for this account on LTI launches"registration\_settings":: returns info about the privacy policy and terms of use"services":: returns services and whether they are enabled (requires account management permissions)"course\_count":: returns the number of courses directly under each account"sub\_account\_count":: returns the number of sub-accounts directly under each account"site\_admin":: returns true if the account is the Site Admin account (only included if true) Allowed values: lti\_guid, registration\_settings, services, course\_count, sub\_account\_count, site\_admin
site\_admin
List of permissions to check against the authenticated user.Permission names are documented in the List assignable permissions endpoint.
If true, the entire account tree underneaththis account will be returned (though still paginated). If false, onlydirect sub-accounts of this account will be returned. Defaults to false.
Sorts the accounts by id or name.Only applies when recursive is false. Defaults to id. Allowed values: id, name
id
name
Array of additional information to include."course\_count":: returns the number of courses directly under each account"sub\_account\_count":: returns the number of sub-accounts directly under each account Allowed values: course\_count, sub\_account\_count
If true, include only courses with at least one enrollment. If false,include only courses with no enrollments. If not present, do not filteron course enrollment status.
If set, only return courses that have at least one user enrolled inin the course with one of the specified enrollment types. Allowed values: teacher, student, ta, observer, designer
teacher
student
ta
observer
designer
If set, only return courses that have at least one user enrolled inin the course with one of the specified enrollment workflow states. Allowed values: active, completed, deleted, invited, pending, creation\_pending, rejected, inactive
active
completed
deleted
invited
pending
creation\_pending
rejected
inactive
If true, include only published courses. If false, exclude publishedcourses. If not present, do not filter on published status.
If true, include only completed courses (these may be in state'completed', or their enrollment term may have ended). If false, excludecompleted courses. If not present, do not filter on completed status.
If true, include only blueprint courses. If false, exclude them.If not present, do not filter on this basis.
If true, include only courses that inherit content from a blueprint course.If false, exclude them. If not present, do not filter on this basis.
If true, include only public courses. If false, exclude them.If not present, do not filter on this basis.
List of User IDs of teachers; if supplied, include only courses taught byone of the referenced users.
List of Account IDs; if supplied, include only courses associated with oneof the referenced subaccounts.
If present, only return courses that have at least one enrollment.Equivalent to 'with\_enrollments=true'; retained for compatibility.
If set, only return courses that are in the given state(s). By default,all states but "deleted" are returned. Allowed values: created, claimed, available, completed, deleted, all
created
claimed
available
all
If set, only includes courses from the specified terms. Can be either a single ID oran array of enrollment term IDs.
- All explanations can be seen in the Course API index documentation- "sections", "needs\_grading\_count" and "total\_scores" are not valid options at the account level Allowed values: syllabus\_body, term, course\_progress, storage\_quota\_used\_mb, total\_students, teachers, account\_name, concluded, post\_manually
syllabus\_body
term
course\_progress
storage\_quota\_used\_mb
total\_students
teachers
account\_name
concluded
post\_manually
The filter to search by. "course" searches for course names, course codes,and SIS IDs. "teacher" searches for teacher names Allowed values: course, teacher
course
If set, only return courses that start before the value (inclusive)or their enrollment term starts before the value (inclusive)or both the course's start\_at and the enrollment term's start\_at are set to null.The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.
If set, only return courses that end after the value (inclusive)or their enrollment term ends after the value (inclusive)or both the course's end\_at and the enrollment term's end\_at are set to null.The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.
Updates the account sis\_account\_idMust have manage\_sis permission and must not be a root\_account.
The default time zone of the account. Allowed time zones areIANA time zones or friendlierRuby on Rails time zones.
The ID of a course to be used as a template for all newly created courses.Empty means to inherit the setting from parent account, 0 means to notuse a template even if a parent account has one set. The course must bemarked as a template.
The ID of a parent account to move the account to. The new parent accountmust be in the same root account as the original. The hierarchy ofsub-accounts will be preserved in the new parent account. The caller mustbe an administrator in both the original parent account and the new parentaccount.
Determines whether this account has Microsoft Teams Sync enabled or not.Note that if you are altering Microsoft Teams sync settings you must enablethe Microsoft Group enrollment syncing feature flag. In addition, if you are enablingMicrosoft Teams sync, you must also specify a tenant, login attribute, and a remote attribute.Specifying a suffix to use is optional.
The tenant this account should use when using Microsoft Teams Sync.This should be an Azure Active Directory domain name.
The attribute this account should use to lookup users when using Microsoft Teams Sync.Must be one of "sub", "email", "oid", "preferred\_username", or "integration\_id".
A suffix that will be appended to the result of the login attribute when associatingCanvas users with Microsoft users. Must be under 255 characters and contain no whitespace.This field is optional.
The Active Directory attribute to use when associating Canvas users with Microsoft users.Must be one of "mail", "mailNickname", or "userPrincipalName".
Suppress notification messages from being created and sent. When set to+true+, all notifications are suppressed. When set to an array ofnotification category slugs (e.g. +\["grading", "announcement"]+), onlynotifications in those categories are suppressed. Set to +false+ toallow all notifications. Root account setting only.
Hash of optional password policy configuration parameters for a root account+allow\_login\_suspension+ boolean:: Allow suspension of user logins upon reaching maximum\_login\_attempts+require\_number\_characters+ boolean:: Require the use of number characters when setting up a new password+require\_symbol\_characters+ boolean:: Require the use of symbol characters when setting up a new password+minimum\_character\_length+ integer:: Minimum number of characters required for a new password+maximum\_login\_attempts+ integer:: Maximum number of login attempts before a user is locked outRequired feature option:Enhance password options
Default is true. If false, any fields containing “sticky” changes will not be updated.See SIS CSV Format documentation for information on which fields can have SIS stickiness
\[Array\]The IDs of the users to update.
The partial name or full ID of the admins to match and return in theresults list. Must be at least 2 characters.
\[DEPRECATED] The user's admin relationship with the account will becreated with the given role. Defaults to 'AccountAdmin'.
Send a notification email tothe new admin if true. Default is true.
Only return experiences with the specified workflow state.Allowed values: published, unpublished, deleted
The initial state of the experience. Defaults to 'unpublished'.Allowed values: published, unpublished
The state of the experience.Allowed values: published, unpublished
If async is true, then the course\_assignments call can happen asynch-ronously and MAY return a response containing a progress\_url key insteadof an assignments array. If it does, then it is the caller'sresponsibility to poll the API again to see if the progress is complete.If the data is ready (possibly even on the first async call) then itwill be passed back normally, as documented in the example response.
List of context\_codes to retrieve announcements for (for example, +course\_123+). Only coursesare presently supported. The call will fail unless the caller has View Announcements permissionin all listed courses.
Only return announcements posted since the start\_date (inclusive).Defaults to 14 days ago. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.
Only return announcements posted before the end\_date (inclusive).Defaults to 28 days from start\_date. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.Announcements scheduled for future posting will only be returned to course administrators.
Only return announcements having locked\_at nil or after available\_after (exclusive).The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.Effective only for students (who don't have moderate forum right).
Only return active announcements that have been published.Applies only to requesting users that have permission to viewunpublished items.Defaults to false for users with access to view unpublished items,otherwise true and unmodifiable.
Only return the latest announcement for each associated context.The response will include at most one announcement for eachspecified context in the context\_codes\[] parameter.Defaults to false.
Optional list of resources to include with the response. May includea string of the name of the resource. Possible values are:"sections", "sections\_user\_count"if "sections" is passed, includes the course sections that are associatedwith the topic, if the topic is specific to certain sections of the course.If "sections\_user\_count" is passed, then:(a) If sections were asked for and the topic is specific to certaincourse sections sections, includes the number of users in eachsection. (as part of the section json asked for above)(b) Else, includes at the root level the total number of users in thetopic's context (group or course) that the topic applies to.
Array of additional information to include."appointments":: calendar event time slots for this appointment group"child\_events":: reservations of those time slots"participant\_count":: number of reservations"reserved\_times":: the event id, start time and end time of reservationsthe current user has made)"all\_context\_codes":: all context codes associated with this appointment group Allowed values: appointments, child\_events, participant\_count, reserved\_times, all\_context\_codes
appointments
child\_events
participant\_count
reserved\_times
all\_context\_codes
Array of context codes (courses, e.g. course\_1) this group should belinked to (1 or more). Users in the course(s) with appropriate permissionswill be able to sign up for this appointment group.
Array of sub context codes (course sections or a single group category)this group should be linked to. Used to limit the appointment group toparticular sections. If a group category is specified, students will signup in groups and the participant\_type will be "Group" instead of "User".
Indicates whether this appointment group should be published (i.e. madeavailable for signup). Once published, an appointment group cannot beunpublished. Defaults to false.
Maximum number of participants that may register for each time slot.Defaults to null (no limit).
Minimum number of time slots a user must register for. If not set, usersdo not need to sign up for any time slots.
Nested array of start time/end time pairs indicating time slots for thisappointment group. Refer to the example request.
"private":: participants cannot see who has signed up for a particulartime slot"protected":: participants can see who has signed up. Defaults to"private". Allowed values: private, protected
private
protected
Array of additional information to include. See include\[] argument of"List appointment groups" action."child\_events":: reservations of time slots time slots"appointments":: will always be returned"all\_context\_codes":: all context codes associated with this appointment group Allowed values: child\_events, appointments, all\_context\_codes
"private":: participants cannot see who has signed up for a particulartime slot"protected":: participants can see who has signed up. Defaults to "private". Allowed values: private, protected
That's correct!
Unfortunately, that IS a prime number.
Goldbach's conjecture proposes that every even integer greater than 2 can be expressed as the sum of two prime numbers.
The UUID of the asset to which the report applies. Canvas will supplythis to the tool in the the LtiAssetProcessorSubmissionNotice.
LtiAssetProcessorSubmissionNotice
A machine-readable code indicating the cause of the failure, for reportswith a processingProgress value of Failed. The following standard errorcodes are available, but tools may use their own (in which case the toolmay provide human-readable information in the comment field):UNSUPPORTED\_ASSET\_TYPE, ASSET\_TOO\_LARGE, ASSET\_TOO\_SMALL,EULA\_NOT\_ACCEPTED, DOWNLOAD\_FAILED
Failed
comment
Alternate text representing the meaning of the indicationColor for screenreaders or as a tooltip over the indication color.
A hex (#RRGGBB) color code the tool wishes to use indicating the outcomeof an asset's report.
A number from 0 (meaning "good" or "success") to 5 (meaning urgent ortime-critical notable features) indicating the tool's perceived priorityof the report. If a priority is not known or applicable, the tool shoulduse the value 0.
Indicates the status of the report. Should be one of the following:Processed, Processing, PendingManual, Failed, NotProcessed, NotReady.If an unrecognized value is given, the value will be stored, but willbe treated by Canvas as NotReady.
NotReady
A short string (16 characters or fewer) that briefly describes thesuccessful result of the processing. This should be provided ifprocessingProgress is Processed, and not provided otherwise.
An ISO8601 date time value with microsecond precision. Reports with newertimestamps for the same asset and report type supersedepreviously submitted reports with older (or equal) timestamps. Likewise,if the timestamp provided is older than the latest timestamp for anexisting report (of same asset and type), the new report will beignored and the endpoint will return an HTTP 409 (Conflict).
A boolean value indicates whether the indicator and reportshould be visible to the user who owns the asset being reported on.If no value is provided, the platform should assume a default value of false
The userId represents the user who has accepted or declined the EULA,lti\_id of the Canvas User.
lti\_id
The timestamp represents the time at which the user accepted or declined the EULA.This timestamp must be formatted as an ISO 8601 date time.
Number of times the student is allowed to re-take the assignment over thelimit.
Associations to include with the group. "discussion\_topic", "all\_dates", "can\_edit","assignment\_visibility" & "submission" are only valid if "assignments" is also included."score\_statistics" requires that the "assignments" and "submission" options are included.The "assignment\_visibility" option additionally requires that the Differentiated Assignments course feature be turned on.If "observed\_users" is passed along with "assignments" and "submission", submissions for observed users will also be included as an array.The "peer\_review" option requires that the Peer Review Grading course feature be turned on and that "assignments" is included. Allowed values: assignments, discussion\_topic, all\_dates, assignment\_visibility, overrides, submission, observed\_users, can\_edit, score\_statistics, peer\_review
assignments
discussion\_topic
all\_dates
assignment\_visibility
overrides
submission
observed\_users
can\_edit
score\_statistics
peer\_review
If "assignments" are included, optionally return only assignments having their ID in this array. This argument may also be passed asa comma separated string.
If "assignments" are included, those with the specified submission typeswill be excluded from the assignment groups. Allowed values: online\_quiz, discussion\_topic, wiki\_page, external\_tool
online\_quiz
wiki\_page
external\_tool
The id of the grading period in which assignment groups are being requested(Requires grading periods to exist.)
If true, all assignments returned will apply to the current user in thespecified grading period. If assignments apply to other students in thespecified grading period, but not the current user, they will not bereturned. (Requires the grading\_period\_id argument and grading periods toexist. In addition, the current user must be a student.)
Associations to include with the group. "discussion\_topic" and "assignment\_visibility" and "submission"are only valid if "assignments" is also included. "score\_statistics" is only valid if "submission" and"assignments" are also included. The "assignment\_visibility" option additionally requires that the Differentiated Assignmentscourse feature be turned on. Allowed values: assignments, discussion\_topic, assignment\_visibility, submission, score\_statistics
The id of the grading period in which assignment groups are being requested(Requires grading periods to exist on the account)
The grading rules that are applied within this assignment groupSee the Assignment Group object definition for format
The ID of an active Assignment Group to which the assignments that arecurrently assigned to the destroyed Assignment Group will be assigned.NOTE: If this argument is not provided, any assignments in this AssignmentGroup will be deleted.
Do the following:
Optional information to include with each assignment:submission:: The current user's current +Submission+assignment\_visibility:: An array of ids of students who can see the assignmentall\_dates:: An array of +AssignmentDate+ structures, one for each override, and also a +base+ if the assignment has an "Everyone" / "Everyone Else" dateoverrides:: An array of +AssignmentOverride+ structuresobserved\_users:: An array of submissions for observed userscan\_edit:: an extra Boolean value will be included with each +Assignment+ (and +AssignmentDate+ if +all\_dates+ is supplied) to indicate whether the caller can edit the assignment or date. Moderated grading and closed grading periods may restrict a user's ability to edit an assignment.score\_statistics:: An object containing min, max, and mean score on this assignment. This will not be included for students if there are less than 5 graded assignments or if disabled by the instructor. Only valid if 'submission' is also included.ab\_guid:: An array of guid strings for academic benchmarks Allowed values: submission, assignment\_visibility, all\_dates, overrides, observed\_users, can\_edit, score\_statistics, ab\_guid
ab\_guid
Optional information:When the root account has the feature newquizzes\_on\_quiz\_page enabledand this argument is set to "Quiz" the response will be serialized into aquiz format;When this argument isn't specified the response will be serialized into anassignment format; Allowed values: Quiz
newquizzes\_on\_quiz\_page
Quiz
Associations to include with the assignment. The "assignment\_visibility" optionrequires that the Differentiated Assignments course feature be turned on. If"observed\_users" is passed, submissions for observed users will also be included.For "score\_statistics" to be included, the "submission" option must also be set.The "peer\_review" option returns peer review sub assignment data if it exists, regardlessof the Peer Review Allocation and Grading feature state. If no peer review sub assignmentexists, the feature must be enabled to receive a null value; otherwise the key is omitted.The "academic\_integrity\_pledge" option returns the account-level academic integritypledge text a student must accept before submitting this assignment. The key is onlypresent when the pledge is enabled for the account; when present but the pledge does notapply to this assignment (e.g. external tool assignments or Canvas Career courses) thevalue is null. Allowed values: submission, assignment\_visibility, overrides, observed\_users, can\_edit, score\_statistics, ab\_guid, peer\_review, academic\_integrity\_pledge
academic\_integrity\_pledge
The position of this assignment in the group when displayingassignment lists.
List of supported submission types for the assignment.Unless the assignment is allowing online submissions, the array shouldonly have one element.If not allowing online submissions, your options are:"online\_quiz""none""on\_paper""discussion\_topic""external\_tool"If you are allowing online submissions, you can have one or manyallowed submission types:"online\_upload""online\_text\_entry""online\_url""media\_recording" (Only valid when the Kaltura plugin is enabled)"student\_annotation" Allowed values: online\_quiz, none, on\_paper, discussion\_topic, external\_tool, online\_upload, online\_text\_entry, online\_url, media\_recording, student\_annotation
none
on\_paper
online\_upload
online\_text\_entry
online\_url
media\_recording
student\_annotation
Allowed extensions if submission\_types includes "online\_upload"Example:allowed\_extensions: \["docx","ppt"]
Only applies when the Turnitin plugin is enabled for a course andthe submission\_types array includes "online\_upload".Toggles Turnitin submissions for the assignment.Will be ignored if Turnitin is not available for the course.
Only applies when the VeriCite plugin is enabled for a course andthe submission\_types array includes "online\_upload".Toggles VeriCite submissions for the assignment.Will be ignored if VeriCite is not available for the course.
Settings to send along to turnitin. See Assignment object definition forformat.
If submission\_types does not include external\_tool,discussion\_topic,online\_quiz, or on\_paper, determines whether or not peer reviewswill be turned on for the assignment.
Whether peer reviews will be assigned automatically by Canvas or ifteachers must manually assign peer reviews. Does not apply if peer reviewsare not enabled.
If true, Canvas will send a notification to students in the classnotifying them that the content has changed.
If present, the assignment will become a group assignment assignedto the group.
If this is a group assignment, teachers have the options to gradestudents individually. If false, Canvas will apply the assignment'sscore to each member of the group. If true, the teacher can manuallyassign scores to each member of the group.
Hash of external tool parameters if submission\_types is \["external\_tool"].See Assignment object definition for format.
The strategy used for grading the assignment.The assignment defaults to "points" if this field is omitted. Allowed values: pass\_fail, percent, letter\_grade, gpa\_scale, points, not\_graded
pass\_fail
percent
letter\_grade
gpa\_scale
points
not\_graded
The day/time the assignment is due. Must be between the lock dates if there are lock dates.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.
The day/time the assignment is locked after. Must be after the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.
The day/time the assignment is unlocked. Must be before the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.
The assignment group id to put the assignment in.Defaults to the top assignment group in the course.
Whether this assignment is only visible to overrides(Only useful if 'differentiated assignments' account setting is on)
Whether this assignment is published.(Only useful if 'draft state' account setting is on)Unpublished assignments are not visible to students.
The grading standard id to set for the course. If no value is provided for this argument the current grading\_standard will be un-set from this course.This will update the grading\_type for the course to 'letter\_grade' unless it is already 'gpa\_scale'.
Whether this assignment should use the Quizzes 2 LTI tool. Sets thesubmission type to 'external\_tool' and configures the external toolattributes to use the Quizzes 2 LTI tool configured for this course.Has no effect if no Quizzes 2 LTI tool is configured.
The maximum number of provisional graders who may issue grades for thisassignment. Only relevant for moderated assignments. Must be a positivevalue, and must be set to 1 if the course has fewer than two activeinstructors. Otherwise, the maximum value is the number of activeinstructors in the course minus one, or 10 if the course has more than 11active instructors.
The user ID of the grader responsible for choosing final grades for thisassignment. Only relevant for moderated assignments.
Boolean indicating if provisional graders' comments are visible to otherprovisional graders. Only relevant for moderated assignments.
Boolean indicating if provisional graders' identities are hidden fromother provisional graders. Only relevant for moderated assignments.
Boolean indicating if provisional grader identities are visible to thethe final grader. Only relevant for moderated assignments.
Boolean indicating if the assignment is graded anonymously. If true,graders cannot see student identities.
The Attachment ID of the document being annotated.Only applies when submission\_types includes "student\_annotation".
Document processors for this assignment. New document processors can only be addedvia the interactive LTI Deep Linking flow (in a browser), not via API token or JWT authentication.Deletion of document processors (passing an empty array) is allowed via API.
The strategy used for grading peer reviews.Defaults to "points" if this field is omitted. Allowed values: pass\_fail, percent, letter\_grade, gpa\_scale, points
The day/time the peer reviews are due. Must be between the lock dates if there are lock dates.Accepts times in ISO 8601 format, e.g. 2025-08-20T12:10:00Z.
The day/time the peer reviews are locked after. Must be after the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2025-08-25T12:10:00Z.
The day/time the peer reviews are unlocked. Must be before the due date if there is a due date.Accepts times in ISO 8601 format, e.g. 2025-08-15T12:10:00Z.
Only applies if the assignment doesn't have student submissions.List of supported submission types for the assignment.Unless the assignment is allowing online submissions, the array shouldonly have one element.If not allowing online submissions, your options are:"online\_quiz""none""on\_paper""discussion\_topic""external\_tool"If you are allowing online submissions, you can have one or manyallowed submission types:"online\_upload""online\_text\_entry""online\_url""media\_recording" (Only valid when the Kaltura plugin is enabled)"student\_annotation" Allowed values: online\_quiz, none, on\_paper, discussion\_topic, external\_tool, online\_upload, online\_text\_entry, online\_url, media\_recording, student\_annotation
The day/time the assignment is due.Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.
List of overrides for the assignment.If the +assignment\[assignment\_overrides]+ key is absent, any existingoverrides are kept as is. If the +assignment\[assignment\_overrides]+ key ispresent, existing overrides are updated or deleted (and new ones created,as necessary) to match the provided list.
The number of submission attempts allowed for this assignment. Set to -1 or null forunlimited attempts.
List of overrides for the peer reviews.When updating overrides:- Include "id" to update an existing override- Omit "id" to create a new override- Omit an override from the list to delete it