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 AB Support for additional plans.

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.

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.

Notes:

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.

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

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 AB Support at Instructure or your sales representative.

Character Set Support

UTF-8 is the recommended character set for transmitting data using AB Connect - AB Connect stores data in UTF-8 and it is the most common character set on the web. However, as adoption for Unicode and UTF-8 has evolved over the life of Academic Benchmarks, we've built support for a few other character sets to support legacy situations. AB Connect supports RESPONSES in UTF-8, latin1, ISO-8859-1 or Windows-1252 character sets.

Note that at this time AB Connect does not support REQUESTS in any character set other than UTF-8.

To request a specific character set response, include the Accept-Charset HTTP header in your request and supply one of the supported values:

• utf-8

• iso-8859-1

• latin1

• windows-1252

In the case that utf-8 is desired, there is no need to actually include the Accept-Charset header as utf-8 is the default.

The AB Connect response includes a Content-Type header indicating the data type (application/json) as well as the character set of the response. E.g.

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 .

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.

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

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.

Walking the List

As mentioned above, AB Connect limits the size of a response to 10 elements by default. This limit only applies to the primary list of elements for the endpoint. E.g. the Standards endpoint will break the Standards list into pages. However, if you request the Standards endpoint to include related Concepts, all Concepts related to each Standard will be returned in the single call regardless of length of the Concepts list.

When responding with a list, AB Connect supplies paging URLs in the links section of the response can use the next and previous links to walk the response list.

The first page of data includes next and last links. The next link supplies the URL to retrieve the next set of data based on your current page size (which is specified by the limit argument and defaults to 10). Note the use of the offset argument above to support the paging. Offset indicates how far into the list you'd like AB Connect to dive when responding to the request.

One of the middle pages of data should include not just next and last but also first and previous links to support bidirectional paging.

If you'd like to make the page responses larger or smaller, you can use the limit parameter. E.g.

In which case, the number of elements from the list that you receive for each request changes. This is also reflected in the links you get in response in order to enable the system to properly track page size as you navigate the list.

Between these two parameters, you should be able to control how your system receives responses and tune it for optimum performance.

No Limits

When would you ever want your response to contain 0 elements? In addition to the object data contained in the response, most endpoints can return data in the meta object (like facets). If you want to explore the meta object without inducing the overhead of processing data elements in the list, set the limit to 0. E.g.

Will return something similar to the following:

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.

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

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

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.

API Change Log

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

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

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 Asset endpoint for details.

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

Single Standard

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

Fetching a Standard

Searching for Standards

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

Finding Sets of Standards

Account Domain Lookups API

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:

Example Request:

Example Response:

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

Brand Configs API

GET /api/v1/brand_variables

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

Will redirect to a static json file that has all of the brand variables used by this account. Even though this is a redirect, do not store the redirected url since if the account makes any changes it will redirect to a new url. Needs no authentication.

Example Request:

GET /api/v1/accounts/:account_id/brand_variables

Scope: url:GET|/api/v1/accounts/:account_id/brand_variables

GET /api/v1/courses/:course_id/brand_variables

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

Will redirect to a static json file that has all of the brand variables used by the provided context. Even though this is a redirect, do not store the redirected url since if the sub-account makes any changes it will redirect to a new url.

Example Request:

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

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:

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

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:

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 .

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

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.

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.

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.

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

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.

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 for details.

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

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

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:

The main directive for filtering entities in AB Connect is the inclusion of the filter parameter in the URL query. This document outlines how to use filtering with AB Connect. Examples are given with different endpoints and objects but the general principles are independent of the object type or endpoint. In any case, the filter limits the results that are returned or updated by the request.

At its simplest, the filtering utilizes the following syntax:

E.g. the following URL retrieves alignable 5th grade math Standards from Kentucky.

That's a bit messy so let's break it down. The first part is the primary resource endpoint.

The next bit is the filter parameter. The square brackets contain the type of object being filtered. In this case, we are limiting the Standards being returned.

The value of the filter argument is the URL encoded filter string.

Let's decode it to make it readable:

That makes it a little more readable and clarifies the intent. The specifics of the field names aren't critical here. See the endpoint specific documentation for an explanation of each field.

Constructing the Filter Statement

At an atomic level, the most common filter statement appears like <property> <comparator> '<value>' but some functions are also supported (e.g. isempty(<property>)).

A <property> would be any attribute of the object being filtered. Examples of a property for a Standard would be level or status. Alternatively, a property can be the attribute of a complex property. E.g. for a Standard, <property> could also be number.raw or disciplines.subjects.code.

A <value> could be any value appropriate for the property in question. Values are delimited with single quotes.

Together, various operators, properties and values combine to build a logical statements. The following operators are supported by AB Connect in order of decreasing precedence by group.

Notes:

• Inequality operators can be used with date, number and text attributes but the results vary by attribute type. Date attributes filter chronologically. Number attributes filter numerically. Text attributes filter alphabetically.

• Custom attributes can be defined as text or numbers. If you aren't sure of the types for your custom attributes, contact for guidance.

• It is possible to create custom attributes with the same name and different data types in different asset types (or when searching across multiple owners). The treatment of inequalities filtering across multiple data types is deterministic but relatively complex and isn't covered here. Where possible, we recommend you avoid this situation by ensuring your custom attributes don't have name conflicts across data types where possible. For details on the way AB Connect handles filtering across mixed types, contact .

Building Complex Statements

AB Connect also supports Boolean operations to combine atomic filter statements into complex statements. You can also use parentheses to group statements together.

• disciplines.subjects.code eq 'MATH' and education_levels.grades.code eq '5' 5th grade math

• document.publication.authorities.descr eq 'Kentucky DOE' and not disciplines.subjects.code eq 'MATH' Standards from Kentucky not related to math

• (disciplines.subjects.code eq 'MATH' and education_levels.grades.code eq '5') or (disciplines.subjects.code eq 'ELA' and education_levels.grades.code eq '7') 5th grade math and 7th grade language arts Standards

Text Filters

One of the major improvements in AB Connect is the text filtering. The text filter is robust, will return results ordered by relevance and includes soft matches like partial matches. The format for text filtering is unique and utilizes a function style notation. There are two formats.

Filtering a Specific Field

When filtering a particular field, include the field name as well as the value you are filtering for: query(<field>, <string>). For example, to filter for Standards that contain the words "adding" and "fractions" in their statement, the filter would look like:

Note that the text filter is a very soft filter and will often return more Standards than you would expect. The results will be ordered by relevance so the top responses are usually the most important. For example, in the query statement above, the system would return Standards that contain the words "adding fractions" first, followed by Standards that contain "adding" or "fractions". It will also return Standards that contain "add", "addition", etc.

To be more specific, break phrases up into separate statements and be explicit about the Boolean operations to join the queries. The following will only return Standards if they contain both "fractions" and some form of derivation of the word "adding".

Filtering Across Multiple Text Fields

To retrieve Standards that have the keywords in any general text field, remove the field name from the query statement: query(<string>). E.g.

When using this approach, the system will search any fields it considers to be a text field. The specific fields vary by endpoint:

• Standards:

  • statement.descr

  • statement.combined_descr

  • statement.addendums.descr

Filtering by Number in Standards

In Standards documents, numbers are often separated, delimited or decorated with symbols (e.g. "24.B (i)"). Trying to ensure users are typing the numbers EXACTLY as they are entered in the Standards document is difficult. For this reason, AB Connect supports a soft match on the Standards' number.raw, number.enhanced, number.prefix_enhanced, number.alternate and number.root_enhanced fields when the query function is used. It treats any separator between alphanumeric values as a break between numbers and looks for Standards that match numbers returning results by how closely they match the results. In the example listed earlier, it will return Standards that have numbers that contain 24, B AND i first without regards to the separators used in the filter. It will follow that with Standards that contain two of the three, then Standards that contain any one of the numbers. Filtering for "24.B.i" will return the same results in the same order as filtering for "24-b-i" and "24.B (i)".

Escaping Single Quotes

In ODATA, literal strings are quoted using single quotes ('). To include a single quote in a string literal in the filter, use a backslash to escape it ('). For example, to search for the word "don't" in Standards, you would use the following filter:

Checking for Empty Properties

Sometimes it is handy to search for properties that are empty. What "empty" means depends on the property type so AB Connect has an isempty function that will match true on objects with no properties, arrays with no elements and scalar properties with null values. For example, the following filter will return all assets that are missing a subject.

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:

The following objects support SIS IDs in the API:

• sis_account_id

• sis_course_id

• sis_group_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)

• lti_1_3_id (for users, a separate value from

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.

• Terms support default

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 .

ePub Exports API

API for exporting courses as an ePub

A CourseEpubExport object looks like:

An EpubExport object looks like:

GET /api/v1/epub_exports

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

A paginated list of all courses a user is actively participating in, and the latest ePub export associated with the user & course.

Returns a list of objects.

POST /api/v1/courses/:course_id/epub_exports

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

Begin an ePub export for a course.

You can use the to track the progress of the export. The export’s progress is linked to with the progress_url value.

When the export completes, use the endpoint to retrieve a download URL for the exported content.

Returns an object.

GET /api/v1/courses/:course_id/epub_exports/:id

Scope: url:GET|/api/v1/courses/:course_id/epub_exports/:id

Get information about a single ePub export.

Returns an object.

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

Assignment Extensions API

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

An AssignmentExtension object looks like:

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:

Example Request:

Example Response:

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

AI Conversations API

API for managing conversations with AI Experiences.

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

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

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

Mark a conversation as completed/deleted

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

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 .

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

Communication Channels API

API for accessing users' email and SMS communication channels.

Bookmarks API

A Bookmark object looks like:

Authentications Log API

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

Canvas Career Experiences API

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

CommMessages API

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

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.

Course Reports API

API for accessing course reports.

Course Quiz Extensions API

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

Announcements API

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

Access Tokens API

A Token object looks like:

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:

Returns a list of objects.

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.

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:

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:

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 .

Admins API

Manage account role assignments

An Admin object looks like:

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:

Returns a list of objects.

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:

Returns an object.

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:

Returns an object.

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 endpoint with user_id set to self, except the “Admins - Add / Remove” permission is not required.

Returns a list of objects.

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

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 array, this is represented by multiple anonymous objects with the same "name" and different "values". For example, if your Asset type is college logos, the University of Michigan Asset may have Color values of blue and yellow. The Color property would appear in the JSON as:

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

{% swagger src="../openapi.yml" path="/assets" method="post" %} openapi.yml {% endswagger %}

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

{% swagger src="../openapi.yml" path="/assets/{guid}" method="get" %} openapi.yml {% endswagger %}

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.

{% swagger src="../openapi.yml" path="/assets/{guid}" method="patch" %} openapi.yml {% endswagger %}

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.

{% swagger src="../openapi.yml" path="/assets" method="delete" %} openapi.yml {% endswagger %}

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

Content Exports API

API for exporting courses and course content

A ContentExport object looks like:

GET /api/v1/courses/:course_id/content_exports

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

GET /api/v1/groups/:group_id/content_exports

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

GET /api/v1/users/:user_id/content_exports

Scope: url:GET|/api/v1/users/:user_id/content_exports

A paginated list of the past and pending content export jobs for a course, group, or user. Exports are returned newest first.

Returns a list of objects.

GET /api/v1/courses/:course_id/content_exports/:id

Scope: url:GET|/api/v1/courses/:course_id/content_exports/:id

GET /api/v1/groups/:group_id/content_exports/:id

Scope: url:GET|/api/v1/groups/:group_id/content_exports/:id

GET /api/v1/users/:user_id/content_exports/:id

Scope: url:GET|/api/v1/users/:user_id/content_exports/:id

Get information about a single content export.

Returns a object.

POST /api/v1/courses/:course_id/content_exports

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

POST /api/v1/groups/:group_id/content_exports

Scope: url:POST|/api/v1/groups/:group_id/content_exports

POST /api/v1/users/:user_id/content_exports

Scope: url:POST|/api/v1/users/:user_id/content_exports

Begin a content export job for a course, group, or user.

You can use the to track the progress of the export. The migration’s progress is linked to with the progress_url value.

When the export completes, use the endpoint to retrieve a download URL for the exported content.

Request Parameters:

Returns a object.

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

Collaborations API

API for accessing course and group collaboration information.

A Collaboration object looks like:

A Collaborator object looks like:

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 .

Error Reports API

An ErrorReport object looks like:

POST /api/v1/error_reports

Scope: url:POST|/api/v1/error_reports

Create a new error report documenting an experienced problem

Performs the same action as when a user uses the “help -> report a problem” dialog.

Request Parameters:

Example Request:

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

Facets are common filter criteria that will help you present useful filter options to your end users. To request a list of facets for your license and filter criteria, use the facet argument in the GET query. The results are returned in the meta section of the response.

The form of the request is:

facet=<CSV list of facet attributes>

Calculating the facet summaries returned in the meta.facet section of the response does incur some calculation overhead. It is negligible in most circumstances but you have control over how much faceting the server performs. The URL query parameter facet_summary allows you to specify which data fields are processed with the call. A few useful examples:

• facet_summary=*

Account Calendars API

API for viewing and toggling settings of account calendars.

When there is a need to quickly identify and refer to a filtered collection of standards, the "Standard Collection" is what provides a solution. Standard Collection stores the filters object with a name and a guid as reference.

• The "filters" is a JSON object that stores "filters (standard hierarchy)", "globalFilters". Searching filters are generated from this object to narrow down the result set the client wants to use.

• The "name" identifies the standard collection in human readable format.

Content Security Policy Settings API

Conferences API

API for accessing information on conferences.

Blackout Dates API

API for accessing blackout date information.

ePortfolios API

An ePortfolio 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.