Instructure's Developer Portal is your gateway to integrating our learning management system with other tools, automating workflows, and building custom applications. Designed for flexibility and ease of use, our APIs and resources empower developers to create dynamic, efficient learning solutions. Start exploring and bring your ideas to life with the support of our comprehensive documentation and tools.

Alternatively, consider the following choices

Welcome

Welcome to the AB Connect interactive documentation. The documentation and related API were developed to help you integrate AB Connect data and decision support services into your system to power the discovery of your content as well as its relationships to academic standards (e.g. alignments) and other content. AB Connect is built upon the most comprehensive collection of connected K-12 standards metadata, machine learning algorithms and subject matter expert validation available.

If you find your users asking questions like the following, AB Connect has a solution for you.

• I have a standard from Texas, is there a similar standard statement in Arizona?

• I have a very useful lesson plan that is aligned to a Florida standard, but I'm teaching in California. What California standard might this lesson plan help me fulfill?

• I have a very useful lesson plan aligned to a Nevada standard. Are there other similar lesson plans aligned to other state standards that I might use?

• I want to create a lesson around the topic of equivalent numbers. Is there instructional material related to this topic that I can use to build my lesson?

• I have an assessment item covering mass and energy equivalence. Is there any instructional material I could use to reinforce this concept?

• I started tagging my assessment items with a few main concepts. What other concepts within standards may be related to these main concepts?

• I have a lesson plan that is covering divisibility rules. What standards across 50 states cover this concept? What other materials cover this concept?

• I have lessons aligned to Ohio's 2011 Science standards and they've just released the 2018 standards. How can I remap my alignments quickly?

This documentation describes the AB Connect API in great detail offering examples and an interactive to get you started right away. We invite you to learn more about AB Connect or take a test drive. to see working examples built using AB Connect.

© 2024 Instructure, Inc. All rights reserved.

Technical Overview

Version 4.1 of AB Connect is and is structurally compliant with . Since JSON API does not explicitly state syntax of filter statements, Academic Benchmarks adopted a simple filtering syntax based on 's query $filter. Note that ODATA's syntax is not directly compatible with JSON API but was the inspiration for our solution.

Getting Started

When you send data through the interactive endpoints in the , you must authenticate in order to make the call and the responses are handled by a production Academic Benchmarks server so the functionality is real and complete.

If you are already a licensed customer and don't know your credentials or would like to inquire about purchasing a license, please reach out to at Instructure.

If you are not a customer but would like to become familiar with the API, you can request a sandbox account .

Explore Instructure's portfolio of services, including the Elevate Standards Alignment API, Catalog, Canvas LMS, and more! Below you can find a comprehensive overview of tools and platforms designed to enhance educational experiences and administrative functionalities.

There are several URL Parameters where you will need to name specific properties of an object (like filter and fields). Generally speaking, see the endpoint's Response Attributes section for the properties that are available. Here are a few rules to keep in mind when constructing the property names.

• The name of a property on an object is addressed using dot notation like object.property. E.g. disciplines.grades

• JSON constructs in AB Connect responses that are inserted simply to adhere to JSON API requirements are not included in the property naming. E.g. if you want to address the standard_type of a standard object, the name is simply standard_type - not data.attributes.standard_type. Generally speaking, JSON API keywords can be left out of the names - things like attributes, relationships and data. Note that meta properties on relationships are the acception. We include the meta part of the property path to eliminate conflicts between object and relationship property names.

Access to the Academic Benchmarks data and services is licensed by breadth of coverage (authority and subject area) as well as depth of metadata and functionality. If you attempt to access a feature or piece of data and receive a 401 error, check your credentials and the details of the error message body. It may be that your current license does not support the call you are making. In some instances, you'll get a valid response, but the data related to one of these features will simply not be included in the response. E.g. if you are licensed for Standards, but not Topics, when you retrieve a Standard the topics relationship will not exist.

To clarify or discuss your licensing, contact AB Support at Instructure or your sales representative.

Errors are returned as HTTP codes in the 4XX range. All errors are accompanied by a JSON response that provides the details of the error so corrective action can be taken.

    {
      "errors": [
        {
          "source": {
            "pointer": "a JSON Pointer RFC6901 to the associated entity in the request document E.g. \"/data\" for a primary data object, or \"/data/attributes/title\" for a specific attribute.",
            "parameter": "a string indicating which URI query parameter caused the error."
          },
          "detail": "<long error message>",
          "status": "<error code - same as HTTP status code>",
          "title": "<brief error message - typically same as the HTTP status title>"
        },
        ...
      ]
    }

See the documentation for the individual endpoint for the specifics of the errors that apply to that endpoint.

Hello! Welcome to Instructure's Developer Documentation portal.

This portal contains API documentation for all Instructure products.

Below are some examples of things you can do using Instructure product APIs:

Integrate Canvas LMS into Your Applications

• Integrate Canvas LMS into your applications.

• For example,

• between Canvas and your SIS or CRM

• Retrieve and assessment results with API

Access Rich Educational Data with Data Access Platform (DAP)

• Access rich educational data with Data Access Platform (DAP)

• For example, get detailed analytics about your student performance

• Create institutional reports

• Or integrate Canvas data into your business intelligence tools

Improve Your Assessments with Quizzes

• Improve your assessments with

• You can quickly create and share quizzes

• You can get quiz results for analysis

• Save time by

Improve Your Classes

• Improve your classes

• With for the students

• about important events or milestones

• on assignments and quizzes

LLM Integration

• If you would like to use the page with LLMs, you can feed the LLM this url:

Quickstart Guide

1. Get Your Access Key

To access API endpoints for most of our services you need to get an Access Key. The way of getting these Access keys may be different for each service. Go into the subsection of the service you would like to use and look for a subpage called Authentication, OAuth, Developer Keys.

Examples:

• For Canvas LMS, find the Get started guide and

• For Data Access Platform,

• For Elevate Standards Alignment,

2. Make Your First Request!

1. Take your authentication key or secret you got in the previous step.

2. Find an API you would like to try.

3. If there is a "Test it" button, you can click on it and test it on the spot.

4. Otherwise, use Postman or Terminal with curl for testing it.

3. Understand the Responses

When you make an API call, you'll typically get a response in JSON format. Here's how to quickly understand and use these responses:

✅ Successful Response (with status 200 or 201):

A successful response usually looks something like this (this is just an example):

Each response includes data fields (like id, name, and course_code) clearly describing what you've requested. You can use these fields directly in your applications.

⚠️ Error Response (status 4xx):

If something goes wrong, you'll get an error response, for example:

Errors come with clear messages indicating the problem. Common issues include authentication errors, incorrect parameters, or permission issues.

📑 Pagination and Large Data:

Some services, for example Canvas LMS, split API calls into multiple pages when you request a lot of data (like a long list of courses or users):

• Check for a Link header in the response, which provides URLs for the next or previous page of results.

• Example header:

You can follow these links to fetch all the data. Find more info about .

🛠️ Helpful Tips:

• Use tools like or browser extensions (like JSONView) to visualize responses clearly.

• Always refer to the specific API's documentation page for detailed descriptions of each data field.

By default, list results are returned in order of decreasing relevance. However, you can specify a sort field using the sort argument in the URL query string. The format of the requests is:

E.g.

You can specify multiple criteria to ensure that items that may have duplicate values in one property have a secondary sort to guarantee order. E.g.

The default behavior is to sort in ascending order by the specified property. However, if you'd like descending order, prepend the property name with a hyphen/minus (U+002D) "-". E.g.

The Providers resource can be used to retrieve information about your Provider account as well as Providers that have shared all or some of their Assets with your organization and Providers with whom you have shared Assets. You can list all of the Providers related to you, filter the list of related Providers or lookup a specific Provider. The response contains the name of the related Provider as well as the Provider's unique GUID and a list of AB taxonomies they have licensed. In the special circumstance where your own Provider object shows up in the response, you will also see relationships listing Providers that are sharing Assets with you (Owners) as well as Providers with whom you are sharing assets (Consumers).

To locate your own Provider object, user the filter parameter and request Providers with ID _me. That is a special constant that matches yourself. While not terribly helpful with the Providers endpoint, you can also use _all as a match on Provider fields to indicate that you want to match on all Providers. This can be used with the owner.id property on the Assets resource where the default behavior is to only list Assets owned by you.

API Change Log

For API resources, such as the API Change Log for additions, changes, deprecations, and removals, view the in the Canvas Community.

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

As adoption of AB Connect increases, We need to ensure all partners have an optimal integration experience. In order to achieve this goal, API controls limit call frequency and payload sizes. Payload sizes have been constrained with a cap on the limit for a page (see Paging Data for details on payload constraints). The remainder of this section describes call throttling also known as rate limiting.

To ensure one client can not adversely affect another client's system performance rate limiting has been implemented on a per account basis. The rate limiting uses a token bucket model backed by Amazon's API Gateway. In summary, each account has a bucket. The system adds 5 tokens to an account's bucket every second and the bucket can hold up to 25 tokens. Each API call an account makes removes one token from the bucket. If you have not made any calls for a period of time and your bucket is full, you can make a burst of up to 25 calls. However, once your bucket is empty, you'll need to wait before making another call or you'll receive an HTTP 429 response.

Some accounts may have different limits and it is possible that these thresholds change over time, so it is recommended that implementation of a client-side throttling solution that is either self-adjusting or is easy to adjust manually. Depending on the client side architecture and implementation language, there may be client side throttling frameworks available that handle the complexity for your system.

If you have a particular need for a larger bucket size or bucket fill rate, contact for additional plans.

Throttling

Canvas includes a built in dynamic throttling mechanism to prevent a single user from abusing the system and causing adverse effects for others. It works by having a rate limit, and a cost for every request. Each request subtracts from your quota, and the quota is automatically replenished over time. In the event that your API request is throttled, you will receive a 429 Forbidden (Rate Limit Exceeded) response. Your application should be prepared for this error, and retry the request at a later time.

To assist applications with planning, every request will return a X-Request-Cost header that is a floating point number of the amount that request deducted from your remaining quota. If throttling is applicable to this request, there will also be a X-Rate-Limit-Remaining header of your remaining quota.

Since the cost of a request is roughly based on the amount of time it takes to process, and the quota (by default) replenishes at a rate faster than real-time, any API client that makes no more than one simultaneous request is unlikely to be throttled. Parallel requests are subject to an additional pre-flight penalty to prevent a large number of incoming requests being able to bring the system down before their cost is counted against their quota. As soon as each request finishes, the pre-flight penalty is credited back to the quota, and only the actual cost of the request is counted.

For applications that go through the OAuth flow and obtain an access token for each user, each access token has its own quota, and the developer need not be concerned with requests from one user causing another user to be throttled.

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

Accessibility Course Scans API

Trigger accessibility course scan

AccessibilityCourseScansController#create

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:

Returns a object.

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

API Endpoint Attributes

Canvas adds attributes to links in returned HTML snippets to make it easier for API consumers to digest the referenced resources. These attributes are as follows:

• data-api-endpoint - A URL where the linked object can be accessed via the API

• data-api-returntype - The type of data returned

For example, consider an assignment description containing a link to a wiki page in the same course. The description returned by the Get Assignment API might look like this:

The currently supported data-api-returntype values are:

• Assignment

• Discussion

• Page

If the API returns a list of objects instead of a single object, the data-api-returntype will be wrapped in square brackets, e.g. [Assignment].

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

The Asset Definition endpoint provides direct access to the properties on Assets. Asset type is an attribute on an Asset.

The Asset Definitions resource can be used to access different asset types for setting up a browse and filter experience on the Asset resource. See the documentation on the Asset endpoint for details.

All calls against the Asset Definitions resource must be implemented as HTTP GET requests, and must include proper Partner Authentication Credentials.

Retrieving Asset Definitions

In its simplest form, you are able to retrieve the details of a specific Asset Definitions resource by appending the AB GUID to the path portion of the URL.

Asset Definitions Fetching

Searching for Asset Definitions

Using filterings, it is possible to retrieve sets of Asset Definitions that match specific criteria. These Asset Definitions are returned in an array of Asset Definitions objects. See the Introduction for an explanation on .

Finding Sets of Assets Definitions

Compound Documents

Compound documents contain multiple collections to allow for side-loading of related objects. Side-loading is desirable when nested representation of related objects would result in potentially expensive repetition. For example, given a list of 50 comments by only 3 authors, a nested representation would include 50 author objects where a side-loaded representation would contain only 3 author objects.

A compound document is a JSON object with two reserved properties ("meta" and "links"). The "meta" property is required and is described below; the "links" property is currently unused but reserved. All other properties of the compound document's root object should be interpreted as collections of model objects. A compound document will always contain at least one collection.

The "meta" property is a JSON object with one recognized property ("primaryCollection"). If present, the "meta.primaryCollection" property will contain the property name of one of the collections in the compound document. The primary collection contains the data most directly associated with the request. Any pagination indicated through a Link header accompanying a compound document applies to the primary collection.

Any remaining collections in a compound document are secondary collections and will contain objects related (perhaps indirectly, through other secondary objects) to those in the primary collection. Secondary collections should never be considered as ordered or complete.

Example:

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

Academic Benchmarks includes a controlled vocabulary of Concepts that has been used for over 15 years to aid in building relationships between content or assessment items (together referred to as Assets) and Standards. AB Connect Content Enrichment tools (Clarifier and prediction engine) are built on top of the Concepts. Each Concept represents a unique notion that a Standard or Asset covers. Academic Benchmarks unpacks Standards into groups of Concepts called key_ideas which can be retrieved via the Standards endpoint. Similarly, Assets can be related to Concepts which can act as an intermediary between Assets and Standards.

Topics are a similar intermediary controlled vocabulary but while Topics are comparatively broad or higher level than Standards, Concepts are very granular and operate at the unpacked Standard level.

The Concepts resource can be used to access the Academic Benchmarks Concepts and related metadata. Use of the API ensures the most current Concepts data is available to your application. At this point in time, the Concepts endpoint is relatively simple as the expectation is that partners will use Standards or Topics as a starting point for building an Asset's metadata profile and then refine it using the Clarifier. However, this endpoint does allow the caller to retrieve context of the Concept which can clarify ambiguous terms.

The relationship between Concepts and other objects are tracked and reported via the other objects. For example, to understand what Concepts a Standard encompasses, retrieve the concepts list via the Standard endpoint (or see the key_ideas field). Similarly, the Asset endpoint can be used to associate Assets with Concepts and retrieve the current relationship. See also the Clarifier endpoint to further explore potential relationships between Concepts, Standards and Assets.

All calls against the Concepts resource must be implemented as HTTP GET requests, and must include proper .

Note that access to AB Concepts is licensed separately. If your credentials are correct and you are still receiving a 401 error (or no results), check with to ensure you are licensed for Concepts. See the section on for a discussion on the licensing required for access to Key Ideas and Concepts.

Single Concept

In its simplest form, you are able to retrieve the details of a specific Concept by appending the AB GUID to the path portion of the URL.

Fetching a Concept

Searching for Concepts

Using filtering and facets, it is possible to retrieve sets of Concepts that match specific criteria. These Concepts are returned in an array of Concept objects. See the Introduction for an explanation on and the use of . This section covers the specifics of using these parameters with the Concepts resource.

Finding Sets of Concepts

The Topics resource can be used to access the Academic Benchmarks Topic Taxonomy and related metadata. The API provides a simple integration point, eliminates the need to maintain a copy of the taxonomy locally and provides the foundation for additional connected metadata. Use of the API ensures the most current taxonomy is available to your application.

One of the benefits of AB Connect is the ability to navigate relationships between Topics and Standards. Topics can also be related to other Topics by the nature of their position in the hierarchy of the Topic Taxonomy (parent/child). Retrieving related Standards and Topics is done in a similar fashion as attributes, but they are contained in the JSON API relationships response. Note that due to the JSON API standard, only the type and ID are returned in the relationship data. Keep in mind that the JSON API ID is the same as the AB GUID for these entities. If you'd like to retrieve the data of the related Standards or Topics, use the include parameter.

Topics can also be related to Assets. Note that if a Topic is related to an Asset, Standards related to that same Topic automatically become related to the Asset as "predicted" (and vice versa). Relationships between Topics and Assets are managed through the Asset endpoint. See the documentation on the Asset endpoint for details.

All calls against the Topics resource must be implemented as HTTP GET requests, and must include proper Partner Authentication Credentials.

Note that the Academic Benchmarks Topic Taxonomy is licensed separately. If your credentials are correct and you are still receiving a 401 error (or no results), check with to ensure you are licensed for Topics.

Single Topic

In its simplest form, you are able to retrieve the details of a specific Topic by appending the AB GUID to the path portion of the URL.

Fetching a Topic

Searching for Topics

Using filtering and facets, it is possible to retrieve sets of Topics that match specific criteria. These Topics are returned in an array of Topics objects. See the Introduction for an explanation on and the use of . This section covers the specifics of using these parameters with the Topics resource.

Finding Sets of Topics

Masquerading

Masquerading is making an API call on behalf of another user. It will behave as if the target user had made the API call with their own access token (even if they don't have one), including permission checks, enrollments, etc. In order to masquerade via the API, the calling user must have the "Become other users" permission. If the target user is also an admin, the calling user must additionally have every permission that the target user has. For auditing purposes, all calls log both the calling user and the target user.

To masquerade, add an as_user_id parameter to any request. It can be either a Canvas user ID, or an SIS user ID (as described in SIS IDs):

curl 'https://<canvas>/api/v1/users/self/activity_stream?as_user_id=sis_user_id:brian' \
     -H "Authorization: Bearer <token>"

Masquerading could be useful in a number of use cases:

• For developing an admin tool

• For accessing APIs that can only be called on self (i.e. the activity stream as shown above)

• For a portal type application that's already tightly integrated with an SIS and is managed by the school, to avoid going through the OAuth flow for every student

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

API Token Scopes API

API for retrieving API scopes

A Scope object looks like:

{
  // 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"
}

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:

Returns a list of objects.

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

All AB Connect v4.1 endpoints deal with lists of data. Unless you are requesting a single element using its GUID (or ID), the response will contain a list - even if there is just a single element in the list. For efficiency reasons, AB Connect breaks the list up into pages. The default page size is 10 elements except for the Clarifier which returns 5 Concepts and 5 Standards by default. The limit and offset arguments help your application manage the list of data by setting the page size and enabling the application to walk through the pages of the list. This way, you can strike the proper balance between efficiency and performance.

Note that in order to maintain server stability, page sizes are capped at 100 objects per page to prevent resource depletion on the server.

This section illustrates the general use of limit and offset but doesn't go into the details of any given particular endpoint.

Account Domain Lookups API

Assignment Extensions API

API for setting extensions on student assignment submissions. These cannot be set for discussion assignments or quizzes. For quizzes, use instead.

An AssignmentExtension object looks like:

Pagination

Requests that return multiple items will be paginated to 10 items by default. You can set a custom per-page amount with the ?per_page parameter. There is an unspecified limit to how big you can set per_page to, so be sure to always check for the Link header.

To retrieve additional pages, the returned Link

Licensing Considerations

Access to the Academic Benchmarks data and services is licensed by breadth of coverage (authority and subject area) as well as depth of metadata and functionality. If you attempt to access a feature or piece of data and receive a 401 error, check your credentials and the details of the error message body. It may be that your current license does not support the call you are making. In some instances, you'll get a valid response, but the data related to one of these features will simply not be included in the response. E.g. if you are licensed for Standards, but not Topics, when you retrieve a Standard the topics relationship will not exist.

To clarify or discuss your licensing, contact at Instructure or your sales representative.

Accounts (LTI) API

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:

Developer Key Account Bindings API

Developer key account bindings API for binding a developer key to a context and specifying a workflow state for that relationship.

A DeveloperKeyAccountBinding object looks like:

Brand Configs API

The Standards resource can be used to access academic Standards and related metadata. The API provides a simple integration point, eliminates the need to manage Standards data in your organization and system, and provides the foundation for additional connected metadata. Use of the API ensures the most current Standards data is available to your application.

One of the greatest benefits of AB Connect is the ability to navigate relationships between Standards, other Standards and Topics. Retrieving the related Standards and Topics is done in a similar fashion as attributes, but they are contained in the JSON API relationships response. Note that due to the JSON API standard, only the type and ID are returned in the relationship data. Keep in mind that the JSON API ID is the same as the AB GUID for these entities. If you'd like to retrieve the data of the related resources, use the include parameter.

Standards can also be related to Assets. Note that if a Standard is related to an Asset, Topics related to that same Standard automatically become related to Asset as "predicted" relationships when you are licensed for the Academic Benchmarks Topic Taxonomy. Note that this implied relationship is bidirectional, so relating a Topic to an Asset directly also generates predicted Standards relationships. Relationships between Standards and Assets are managed through the Asset endpoint. See the documentation on the for details.

All calls against the Standards resource must be implemented as HTTP GET requests, and must include proper

Standards evolve over time. An authority may make a major update to their Standards document. In this case, an authority re-issues an updated document that totally replaces the Standards of the past. This results in a new document being added to your license. Alternately, an authority may modify, remove or add individual Standards within the current document. If your organization is caching Standards data, it is important that you keep your cache fresh. While it is possible to purge your cache and retrieve the entire set of Standards periodically, that is inefficient and does not support the maintenance of alignments and other related data. It is more efficient and useful to request differential updates. With AB Connect, you do this using the events endpoint.

In addition to changes to Standards themselves, the events endpoint exposes changes to your access to Standards. Your access can change due to licensing changes or configuration of which Standards you have opted to have delivered. For the context of this documentation, we will refer to Standards as "deliverable" regardless of whether the changes were due to license or configuration changes because Events do not treat the various sources of the change differently. For information on changing your licensing or delivery, contact AB Support.

Delivery Related Events And the Interaction Between Deliverability And Change Events

When a document is added to your delivery, you will receive an Event with target set to document and change_type set to added. This Event indicates that you should request and download the Standards related to the specified document. E.g. you may receive an Event that looks something like:

That would initiate a process that requests Standards related to that document:

Similarly, if you receive an Event with change_type set to removed, your license requires that you purge the related document and references from your system.

Notes:

• Delivery Events can occur on sections as well as documents.

• Events that occur on Standards that are not delivered to you are not visible to you. The filtering of Events by deliverability is time sensitive so you will not receive Events that occurred on Standards that were not deliverable to you at the time of the Event, even if the Standard is deliverable at the time of the call.

• Since Standards changes are delivered based on the status at the time of the Event, it is possible for you to receive Events on Standards that you no longer have access to. So if you receive a change Event for a Standard and your change management process tries to look up the details of the Standard but doesn't have access, silently skip the process because a removed

Accurate Syncing

You can request individual Events but more commonly you would request Events that have occurred since your last sync. In previous versions, the filter for requesting updates focused the filter on the date. However, this can be problematic due to concurrency and race conditions. Now, AB Connect gives each Event a sequence number to ensure no Events are missed. After each refresh, store the sequence number of the last Event you received. Future requests should request Events with sequence numbers greater than the last one you received. E.g. if the last Event you received had a sequence number of 28974, the request may look like:

A couple of important notes about the sequence number:

• Sequence numbers will not appear incremental. Each Event in the system gets a unique number and since the Events include partner specific Events (like changes in license and Standards delivery settings), Events received by any individual partner will not have incremental numbers.

Using Events As A New Partner

New partners can use seq GT 0 to start. Since you will not receive Events that occur before your license was active, you won't be flooded with historical data. The first Events you will see will be Events to add documents (and possibly sections). You can use this approach to do the initial download of the Standards into your cache. However, if you've already downloaded all of the Standards you have access to, you will want to skip this first set of Events.

Developing a Workflow

One of the advantages of using Events is that you can build a workflow around them. You may want to consider caching Events before acting on them in your system. That will allow you to put the changes into an editorial workflow so you can make decisions for accurately updating alignments and other relationships.

For example, if you receive an Event indicating a Standard has been deleted, you may want to flag content aligned to that Standard as being in need of an alignment review.

Unlike Standard change Events, deliverability Events should be acted upon immediately to ensure your system is in line with license agreements.

Retrieving Events

Using filtering, it is possible to retrieve sets of Events. These Events are returned in an array of Events objects. See the Introduction for an explanation on . This section covers the specifics of using these parameters with the Events resource.

A note on filtering Events. Events can be filtered on the properties of the Event object AND on the same subset of properties of the Standards that are listed in the section on . The exceptions are the Event affected_properties.new_value and affected_properties.previous_value fields since those are of variant types.

Finding Series of Events

Object IDs, SIS IDs, and special IDs

Throughout the API, objects are referenced by internal IDs. You can also reference objects by SIS ID, by prepending the SIS ID with the name of the SIS field, like sis_course_id:. For instance, to retrieve the list of assignments for a course with SIS ID of A1234:

/api/v1/courses/sis_course_id:A1234/assignments

The following objects support SIS IDs in the API:

• sis_account_id

• sis_course_id

• sis_group_id

• sis_group_category_id

• sis_integration_id (for users and courses)

• sis_login_id

• sis_section_id

• sis_term_id

• sis_user_id

Some objects support LTI IDs:

• lti_context_id (for accounts, assignments, courses, groups, and users)

• lti_1_1_id (for users, an alias of lti_context_id, which is sent in LTI 1.1 launches as user_id)

Additionally, some objects support special IDs:

• Users support self to mean the current user.

• Accounts support self to mean the root account for the current domain, default to mean the Default account, and site_admin to mean the Site Admin account.

Encoding and Escaping

SIS IDs should be encoded as UTF-8, and then escaped normally for inclusion in a URI. For instance the SIS ID CS/101.11é is encoded and escaped as CS%2F101%2E11%C3%A9.

Note that some web servers have difficulties with escaped characters, particularly forward slashes. They may require special configuration to properly pass encoded slashes to Rails.

For Apache and Passenger, the following settings should be set:

• NoDecode

• on

Also beware that if you use , you should enable the nocanon option. Similarly, should use the , or noescape flag. Other modules may also need additional configuration to prevent double-escaping of %2f (/) as %252f.

Prior versions of this API documentation described using a hex encoding to circumvent these issues, since the proper Apache/Passenger configuration was not known at the time. This format is deprecated, and will no longer be described, but will continue to be handled by the server for backwards compatibility.

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

Accessibility Course Statistics API

An AccessibilityCourseStatistic object looks like:

// 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"
}

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:

Returns a list of objects.

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

Welcome to the Canvas LMS API Documentation

Canvas LMS includes a REST API for accessing and modifying data externally from the main application, in your own programs and scripts. This documentation describes the resources that make up the API.

To get started, you'll want to review the general basics, including the information below and the page on .

AI Conversations API

API for managing conversations with AI Experiences.

CommMessages API

API for accessing the messages (emails, sms, etc) that have been sent to a user.

A CommMessage object looks like:

Academic Benchmarks refers to partner content and assessment items as Assets. In AB Connect, an Asset is the metadata that describes the content - not the actual content itself. The Assets resource can be used to perform a host of operations on partner Assets to allow you to manage and relate your Assets. You can create, modify and delete Assets. You can also build a metadata profile for your Assets which allow you to take advantage of the power of the AB Connect prediction engine to establish and maintain relationships between your Asset, Standards and other Assets. See the section on Licensing Considerations for a discussion on the licensing required for access to Assets.

In addition to the attributes and relationships built into AB Connect to support Content Enrichment and predictions, AB Connect allows you to define your own attributes to support needs such as advanced searching. These customer defined attributes are referred to as descriptors or custom attributes. They can be configured per Asset type either by you (if you have web access enabled for your account) or by AB Support.

Custom attributes are represented in the API in two ways: through the descriptors array or by direct named properties of the custom_attributes object property. The name of the property is defined in the Asset setup screens. The descriptors array was the initial implementation and has been kept for backwards compatibility but the direct named attributes are easier to work with (particularly when filtering) and are the recommended approach. To illustrate the payload for custom attributes, if the Asset type has a property named "Color", it will be represented in the descriptors array as an anonymous name/value pair like:

However, it will also be represented as a named attribute like:

A couple of key points:

• When custom attributes are exchanged in JSON as named attributes, they are converted to lower case and any spaces or special characters are replaced by underscores. Multiple underscores in a row are collapsed into a single underscore. You won't need to think too much about this because the Asset type setup screen shows both the full property name and the JSON API attribute property name.

• It is the responsibility of the client application to control the values of the custom attributes, so if you have single-valued properties or controlled vocabularies in your use case, ensure they are handled properly before sending the data to AB Connect.

• The named attribute is an array. This is because custom attributes are multi-valued in AB Connect. In the descriptors

And:

Finally, all calls against the Asset resource must be implemented as HTTP GET, POST, DELETE or PATCH requests, and must include proper .

Creating an Asset

To create an Asset within the AB Connects system, you send a POST to the endpoint. The body of the POST contains the Asset definition in JSON format. The only required fields are client_id and asset_type. You can define your asset_type using the Academic Benchmarks web interface or have support set it up for you. If you do not know your asset_type or need to have one setup for you, contact for details.

Note: The Asset endpoint allows you to manipulate basic attributes of the Asset. To manage relationships, see the section on .

Creating an Asset

Retrieving Assets

To work with an Asset, you've created, call the endpoint with a GET while supplying the AB GUID for the Asset. If you have your organization's ID for the Asset but not the AB GUID, see the section on and search on client_id to retrieve the AB GUID.

Retrieving the Details of an Asset

Working with Assets

To work with an Asset you've created, call the endpoint while supplying the AB GUID for the Asset. If you have your organization's ID for the Asset but not the AB GUID, see the section on and search on client_id to retrieve the AB GUID.

Modifying an Asset

To update an Asset, PATCH the Asset URL (with GUID) sending JSON in the body similar to that in the create statement. The JSON body only needs to contain the attributes that need to be updated. You cannot update the client_id or asset_type once the Asset is created. If one of those needs to change, you will need to delete the old Asset and create a new one.

Notes on PATCHing Assets:

1. You do not need to include every field in a PATCH body. However, any field you include will replace the current value of that field on the Asset. For simple fields like title, that's not surprising. However, if you PATCH an object or array, you need to send the final state of that array or object - not just a single element. E.g. if the Asset has a descriptor with 5 name/value pairs on it and you send a PATCH to change 1 name/value pair, be sure to have copies of the other 4 name/value pairs in the descriptor array or the resulting Asset will only have one descriptor name/value pair.

2. If you are doing a bulk update of Assets where you are requesting a large number of Assets, paging through the list and PATCHing the Assets as you page, be sure to sort the list on a field you are not modifying - preferably on a unique fields like the GUID. If you leave the sort order to the default (relevance) or sort on a field you are changing, you will likely get duplicate and skipped Assets as you page through the list.

Deleting Assets

To delete an Asset you've created, call the endpoint while supplying the AB GUID for the Asset. If you have your organization's ID for the Asset but not the AB GUID, see the section on and search on client_id to retrieve the AB GUID.

Deleting an Asset

Assets can be deleted by sending a DELETE to their "self" URL.

Searching for Assets

Using filtering it is possible to retrieve sets of Assets that match specific criteria. These Assets are returned in an array of Asset objects. See the Introduction for an explanation on and . This section covers the specifics of using filtering with the Assets resource.

To find Assets related to Standards, search based on the Standard GUID in the alignments.id field. E.g.

A similar approach can be applied to Topics and Concepts.

If you have your organization's identifier for the Asset, but not the AB GUID for it, you can retrieve the GUID by doing a search on client_id to locate the Asset. E.g.

filter[assets]=(client_id eq 'AJIH-45679')

Searching for Assets Owned by Another Provider

With AB Connect, it is possible to share your Assets with other AB Connect customers (Providers) to facilitate application interoperability. You can allow other Providers (the Consumer) to search sets of your Assets and retrieve the metadata profile describing your content. See the section on the endpoint for an overview.

Assets include an owner relationship that references the object of the Provider to which the Asset belongs. By default, the Assets endpoint only searches the Assets you own. To search the Assets of other Providers, include owner.id in your filter criteria. You can get the IDs of the Owners to which you have access using the Providers endpoint. Alternatively, you can use the special keyword _all to search across all repositories to which you have access. E.g. filter[assets]=owner.id eq _all. You can also use the keyword _me to limit the search to just the Assets you own, but this is redundant with the approach of not specifying the owner.id at all.

Note that if you are including other Owners in your request, you can not include custom_attributes. Cross-owner searches can only operate on built-in properties.

Executing the Search

Finding Sets of Assets

Authentications Log API

Query audit log of authentication events (logins and logouts).

For each endpoint, a compound document is returned. The primary collection of event objects is paginated, ordered by date descending. Secondary collections of logins, accounts, page views, and users related to the returned events are also included. Refer to the Logins, Accounts, Page Views, and Users APIs for descriptions of the objects in those collections.

Authentication logs are stored for one year.

An AuthenticationEvent object looks like:

GET /api/v1/audit/authentication/logins/:login_id

Scope: url:GET|/api/v1/audit/authentication/logins/:login_id

List authentication events for a given login.

Request Parameters:

GET /api/v1/audit/authentication/accounts/:account_id

Scope: url:GET|/api/v1/audit/authentication/accounts/:account_id

List authentication events for a given account.

Request Parameters:

GET /api/v1/audit/authentication/users/:user_id

Scope: url:GET|/api/v1/audit/authentication/users/:user_id

List authentication events for a given user.

Request Parameters:

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

BlockEditorTemplate API

Block Editor Templates are pre-build templates that can be used to create pages. The BlockEditorTemplate API allows you to create, retrieve, update, and delete templates.

A BlockEditorTemplate object looks like:

{
  // the ID of the page
  "id": 1,
  // name of the template
  "name": "Navigation Bar",
  // description of the template
  "description": "A bar of links to other content",
  // the creation date for the template
  "created_at": "2012-08-06T16:46:33-06:00",
  // the date the template was last updated
  "updated_at": "2012-08-08T14:25:20-06:00",
  // The JSON data that is the template
  "node_tree": null,
  // The version of the editor that created the template
  "editor_version": "1.0",
  // The type of template. One of 'block', 'section', or 'page'
  "template_type": "page",
  // String indicating what state this assignment is in.
  "workflow_state": "unpublished"
}

GET /api/v1/courses/:course_id/block_editor_templates

Scope: url:GET|/api/v1/courses/:course_id/block_editor_templates

A list of the block templates available to the current user.

Request Parameters:

Example Request:

Returns a list of objects.

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

Canvas Career Experiences API

API for managing user career experience and role preferences in Canvas.

An ExperienceSummary object looks like:

{
  // The current active experience. One of: 'academic', 'career_learner',
  // 'career_learning_provider'.
  "current_app": "career_learner",
  // List of available experiences for the user. Can include: 'academic',
  // 'career_learner', 'career_learning_provider'.
  "available_apps": ["academic", "career_learner"]
}

GET /api/v1/career/enabled

Scope: url:GET|/api/v1/career/enabled

Returns whether the root account has Canvas Career (Horizon) enabled in at least one subaccount.

Example Request:

Example Response:

GET /api/v1/career/experience_summary

Scope: url:GET|/api/v1/career/experience_summary

Returns the current user’s active experience and available experiences they can switch to.

Example Request:

Returns an object.

POST /api/v1/career/switch_experience

Scope: url:POST|/api/v1/career/switch_experience

Switch the current user’s active experience to the specified one.

Request Parameters:

Example Request:

POST /api/v1/career/switch_role

Scope: url:POST|/api/v1/career/switch_role

Switch the current user’s role within the current experience.

Request Parameters:

Example Request:

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

Conferences API

API for accessing information on conferences.

A ConferenceRecording object looks like:

{
  "duration_minutes": 0,
  "title": "course2: Test conference 3 [170]_0",
  "updated_at": "2013-12-12T16:09:33.903-07:00",
  "created_at": "2013-12-12T16:09:09.960-07:00",
  "playback_url": "http://example.com/recording_url"
}

A Conference object looks like:

{
  // The id of the conference
  "id": 170,
  // The type of conference
  "conference_type": "AdobeConnect",
  // The 3rd party's ID for the conference
  "conference_key": "abcdjoelisgreatxyz",
  // The description for the conference
  "description": "Conference Description",
  // The expected duration the conference is supposed to last
  "duration": 60,
  // The date that the conference ended at, null if it hasn't ended
  "ended_at": "2013-12-13T17:23:26Z",
  // The date the conference started at, null if it hasn't started
  "started_at": "2013-12-12T23:02:17Z",
  // The title of the conference
  "title": "Test conference",
  // Array of user ids that are participants in the conference
  "users": [1, 7, 8, 9, 10],
  // Array of user ids that are invitees in the conference
  "invitees": [1, 7, 8, 9, 10],
  // Array of user ids that are attendees in the conference
  "attendees": [1, 7, 8, 9, 10],
  // True if the conference type has advanced settings.
  "has_advanced_settings": false,
  // If true the conference is long running and has no expected end time
  "long_running": false,
  // A collection of settings specific to the conference type
  "user_settings": {"record":true},
  // A List of recordings for the conference
  "recordings": null,
  // URL for the conference, may be null if the conference type doesn't set it
  "url": null,
  // URL to join the conference, may be null if the conference type doesn't set it
  "join_url": null,
  // The type of this conference's context, typically 'Course' or 'Group'.
  "context_type": null,
  // The ID of this conference's context.
  "context_id": null
}

GET /api/v1/courses/:course_id/conferences

Scope: url:GET|/api/v1/courses/:course_id/conferences

GET /api/v1/groups/:group_id/conferences

Scope: url:GET|/api/v1/groups/:group_id/conferences

Retrieve the paginated list of conferences for this context

This API returns a JSON object containing the list of conferences, the key for the list of conferences is “conferences”

Example Request:

Returns a list of objects.

GET /api/v1/conferences

Scope: url:GET|/api/v1/conferences

Retrieve the paginated list of conferences for all courses and groups the current user belongs to

This API returns a JSON object containing the list of conferences. The key for the list of conferences is “conferences”.

Request Parameters:

Example Request:

Returns a list of objects.

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

One of the challenges with adopting a new integration is coming up to speed on the basics of interacting with the partner system. To lower the slope of the learning curve, Academic Benchmarks has documented examples and developed apps. We are sharing the source to give developer's working examples of how to integrate with AB Connect.

Below are brief descriptions of efficient means for implementing solutions and useful examples apps with links to the Instructure Github repository where they can be downloaded. All samples and apps are offered as-is with no warranty. Although they are often usable as is, the main purpose is to illustrate how to interact with the AB Connect API. If any particular app doesn't do what you need, feel free to download a copy and modify it to meet your needs. This repository is not meant to host solutions for non-technical users nor is it a location to submit requests for changes or additions to the API or the samples listed here. Be sure to read the ReadMe for each app for details.

Standards Relationships Browser

Among other things, AB Connect exposes the relationships between Standards. This app is a web page client that allows the user to browse Standards in their license, view the metadata profile of the Standard and find related Standards in other documents. The user is allowed to select from a set of relationships types when navigating across relationships. The types of relationships that are available is based on the licensing of the account used. If the account is not licensed for relationships, the app falls back to a simple Standards browser. This app is also an example of an integration with the embeddable Standards Browser widget (see ). You can find the source in the relationships-browser folder of our . You can find a .

Simple Standards Browser

This is a very simple example app that does little more than illustrate a minimal integration with the embeddable Standards Browser widget. This app is a web page client that allows the user to browse Standards in their license and view the metadata profile of the Standard. See below for more information. You can find the source in the standards-browser-min folder of our . You can find a .

Browse Standards by Topic

AB Connect includes a few taxonomies that can aid in the navigation of Standards and searchability of Assets. The Topics Browser is a basic example of how one could use topics to locate relevant Standards. You can find the source in the topicsBrowser folder of our . You can find a .

Show Alignments On Your Content Page

This example app is designed to give you a quick leg up on showing alignments on your web site. This small sample allows the user to search for content by client_id (usually your internal ID for the content), AB Asset GUID or general text search. It then shows the alignments for the first Asset it finds in AB Connect that matches the search criteria. The user can narrow the scope of the authorities to show only alignments in one state (for example). You can find the source in the display-alignments folder of our .

Content Browser

This is a web page client that allows the user to use faceting to search their Asset repository on AB Connect. Note that the app requires that the account already has a set of Assets and at least a minimal configuration that should take a couple of minutes to get it up and running in a demo mode. You can find the source in the asset-browser folder of our .

Standards Relationships Report

This example is similar to the browser app but is a node.js based and generates a report with a mapping of a set of Standards from one document to another. The input and output are done through Excel files. There is a template supplied as part of the repository. You'll need to use another means for gathering the input which is a set of Standard GUIDs. One quick way to build the list is to use something like Postman to gather the Standards of interest. You can find the source in the relationships-report folder of our .

Standards Browser Widget Source

The source for the Standards Browser Widget documented in is accessable as well. This is a more complex example that spends more effort on the quality of the look and user experience. Where the other examples are good for accelerating API ramp up, the widget source code is best suited to situations where the widget itself is close to meeting your organization's needs but you need to add or modify some features. In that case, start with the existing widget and extend it to meet your needs. You can download the latest .

Here are basic instructions for building the supplied source for distribution. All commands must be executed in the directory where you've unzipped the source.

1. Download the .

2. Unzip the file into a folder on your system.

3. Run the following commands in the folder where you placed the unzipped source.

4. npm install

To obtain a production widgets bundle, follow these steps:

1. For a bash shell:

   1. NODE_ENV=production npm run build

2. For Windows cmd.exe:

Postman Collections

The illustrative-postman-collections folder in our hosts a set of Postman collections that can help get you started with API calls for various scenarios. The ReadMe file gives the details of the available collections.

Collaborations API

API for accessing course and group collaboration information.

A Collaboration object looks like:

{
  // The unique identifier for the collaboration
  "id": 43,
  // A name for the type of collaboration
  "collaboration_type": "Microsoft Office",
  // The collaboration document identifier for the collaboration provider
  "document_id": "oinwoenfe8w8ef_onweufe89fef",
  // The canvas id of the user who created the collaboration
  "user_id": 92,
  // The canvas id of the course or group to which the collaboration belongs
  "context_id": 77,
  // The canvas type of the course or group to which the collaboration belongs
  "context_type": "Course",
  // The LTI launch url to view collaboration.
  "url": null,
  // The timestamp when the collaboration was created
  "created_at": "2012-06-01T00:00:00-06:00",
  // The timestamp when the collaboration was last modified
  "updated_at": "2012-06-01T00:00:00-06:00",
  "description": null,
  "title": null,
  // Another representation of the collaboration type
  "type": "ExternalToolCollaboration",
  // The LTI launch url to edit the collaboration
  "update_url": null,
  // The name of the user who owns the collaboration
  "user_name": "John Danger"
}

A Collaborator object looks like:

{
  // The unique user or group identifier for the collaborator.
  "id": 12345,
  // The type of collaborator (e.g. 'user' or 'group').
  "type": "user",
  // The name of the collaborator.
  "name": "Don Draper"
}

GET /api/v1/courses/:course_id/collaborations

Scope: url:GET|/api/v1/courses/:course_id/collaborations

GET /api/v1/groups/:group_id/collaborations

Scope: url:GET|/api/v1/groups/:group_id/collaborations

A paginated list of collaborations the current user has access to in the context of the course provided in the url. NOTE: this only returns ExternalToolCollaboration type collaborations.

Returns a list of objects.

GET /api/v1/collaborations/:id/members

Scope: url:GET|/api/v1/collaborations/:id/members

A paginated list of the collaborators of a given collaboration

Request Parameters:

Example Request:

Returns a list of objects.

GET /api/v1/courses/:course_id/potential_collaborators

Scope: url:GET|/api/v1/courses/:course_id/potential_collaborators

GET /api/v1/groups/:group_id/potential_collaborators

Scope: url:GET|/api/v1/groups/:group_id/potential_collaborators

A paginated list of the users who can potentially be added to a collaboration in the given context.

For courses, this consists of all enrolled users. For groups, it is comprised of the group members plus the admins of the course containing the group.

Returns a list of objects.

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

GraphQL API

GraphQL Introduction

GraphQL is a query API language that executes queries by using a type system based on defined input data. GraphQL provides more specific inquiries with faster results and populate multiple inputs into one query.

Note: GraphQL endpoint permissions mirror permissions for the REST API. A user is only granted access to view grades based on that user’s permissions. For instance, a student cannot view grades for another student, but an instructor can view grades for any student in a course.

.

Using GraphQL

Canvas has included the tool , an in-browser graphical interface for interacting with GraphQL endpoints.

The GraphiQL interface can be viewed by adding /graphiql to the end of your Canvas production URL (e.g. your-institution.instructure.com/graphiql).

The /graphiql access can also be added to a test or beta environment URL. Requests from the selected environment will always return that environment’s data.

The Explorer sidebar displays all available queries and mutations. Any selected items display in the GraphiQL window. Once a query or mutation is selected, any values displayed in purple text identify the value as an input argument.

REST vs GraphQL

The Canvas REST API will continue to be available.

Fields are being added to the GraphQL API on an as-needed basis. The GraphQL API does not include everything that is currently in the REST API. Feel free to submit pull requests on github to add additional features or talk about it in the #canvas-lms channel on libera.chat.

GraphQL Endpoint

POST /api/graphql

All GraphQL queries are posted to this endpoint.

Request Parameters

Example Request:

Example Response

GraphQL in Canvas

id vs _id and the node field

The Canvas LMS GraphQL API follows the . Querying for an object's id will return a global identifier instead of the numeric ids that are used in the REST API. The traditional ids can be queried by requesting the _id field.

Most objects can be fetched by passing their GraphQL id to the node field:

A legacyNode field is also available to fetch objects via the REST-style ids:

For commonly accessed object types, type-specific fields are provided:

Pagination

Canvas follows the for paginating collections. Request reasonable page sizes to avoid being limited.

Total Count in Connections

Some connection types support a totalCount field in pageInfo that provides the total number of items in the connection, regardless of pagination limits. This is useful for displaying "Page X of Y" pagination interfaces.

Note: totalCount is only available on connections that have been explicitly configured for it. Not all connection types support this field.

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

Announcement External Feeds API

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:

{
  // 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"
}

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:

Returns a list of objects.

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:

Example Request:

Returns an object.

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:

Returns an object.

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

Course Reports API

API for accessing course reports.

A Report object looks like:

{
  // The unique identifier for the report.
  "id": 1,
  // 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 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
}

A ReportParameters object looks like:

// The parameters returned will vary for each report.
{
  
}

GET /api/v1/courses/:course_id/reports/:report_type/:id

Scope: url:GET|/api/v1/courses/:course_id/reports/:report_type/:id

Returns the status of a report.

Example Request:

Returns a object.

POST /api/v1/courses/:course_id/reports/:report_type

Scope: url:POST|/api/v1/courses/:course_id/reports/:report_type

Generates a report instance for the account. Note that “report” in the request must match one of the available report names.

Request Parameters:

Returns a object.

GET /api/v1/courses/:course_id/reports/:report_type

Scope: url:GET|/api/v1/courses/:course_id/reports/:report_type

Returns the status of the last report initiated by the current user.

Example Request:

Returns a object.

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

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

For example, the corresponding scope for the GET /api/v1/courses/:course_id/rubrics API endpoint would be

How do developer key scopes function?

When requesting an access token, third-party applications should specify a scope parameter (see the ). 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 . Scopes may also be found beneath their corresponding endpoints in the "resources" documentation pages.

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 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 ). 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 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 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 .

Announcements API

API for retrieving announcements. This API is Announcement-specific. See also the Discussion Topics API, which operates on Announcements also.

List announcements

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:

Example Request:

Example Response:

Returns a list of objects.

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

Course Quiz Extensions API

API for setting extensions on student quiz submissions at the course level

A CourseQuizExtension object looks like:

{
  // The ID of the Student that needs the quiz extension.
  "user_id": 3,
  // Number of times the student is allowed to re-take the quiz over the
  // multiple-attempt limit.
  "extra_attempts": 1,
  // Amount of extra time allowed for the quiz submission, in minutes.
  "extra_time": 60,
  // The student can take the quiz even if it's locked for everyone else
  "manually_unlocked": true,
  // The time at which the quiz submission will be overdue, and be flagged as a
  // late submission.
  "end_at": "2013-11-07T13:16:18Z"
}

POST /api/v1/courses/:course_id/quiz_extensions

Scope: url:POST|/api/v1/courses/:course_id/quiz_extensions

Responses

• 200 OK if the request was successful

• 403 Forbidden if you are not allowed to extend quizzes for this course

Request Parameters:

Example Request:

Example Response:

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

Access Tokens API

A Token object looks like:

Bookmarks API

A Bookmark object looks like:

Admins API

Manage account role assignments

An Admin object looks like:

Content Exports API

API for exporting courses and course content

A ContentExport object looks like:

Course Audit log API

Query audit log of course events.

For each endpoint, a compound document is returned. The primary collection of event objects is paginated, ordered by date descending. Secondary collections of courses, users and page_views related to the returned events are also included.

The event data for ConcludedEventData, UnconcludedEventData,

Communication Channels API

API for accessing users' email and SMS communication channels.

In this API, the :user_id parameter can always be replaced with self if the requesting user is asking for his/her own information.

A CommunicationChannel object looks like: